Configuration

Configuration of the machine-access-control (MAC) server is accomplished by some JSON configuration files and optional environment variables, as detailed below.

users.json

Users are configured via a users.json file in the current directory, or another file name/path specified in the USERS_CONFIG environment variable. This file defines all of the users and their contact information, as well as their RFID fob code(s) and the authorizations/trainings they have. If using the Neon One CRM, this file can be auto-generated from your CRM Accounts via the NeonOne Integration.

The schema of this file is as follows:

type	array
items	type	object
	properties
	fob_codes	List of fob codes for user.
		type	array
		items	type	string
	account_id	Unique Account ID for user.
		type	string
	full_name	Full name of user.
		type	string
	first_name	First name of user.
		type	string
	preferred_name	Preferred name of user.
		type	string
	email	User email address.
		type	string
	expiration_ymd	User membership expiration in YYYY-MM-DD format.
		type	string
	authorizations	List of authorized field names for user.
		type	array
		items	type	string
	additionalProperties	False

machines.json

Machines are configured via a machines.json file in the current directory, or another file name/path specified in the MACHINES_CONFIG environment variable. This file lists all of the supported/configured machines and which authorization(s) are required to use them. Note that the names in this file must match the names configured in your ESPHome Hardware. Machine names must be unqiue and can only contain alphanumeric characters, underscores, and dashes. No spaces, no dots.

The schema of this file is as follows:

type	object
patternProperties
^[a-z0-9_-]+$	Unique machine name, alphanumeric _ and - only.
	type	object
	properties
	authorizations_or	List of authorizations required to operate machine, any one of which is sufficient.
		type	array
		items	type	string
	unauthorized_warn_only	If set, allow anyone to operate machine but log and display a warning if the operator is not authorized.
		type	boolean
	additionalProperties	False

Environment Variables

Environment Variables
Variable	Required?	Description
`USERS_CONFIG`	no	path to users configuration file; default `./users.json`
`MACHINES_CONFIG`	no	path to machines configuration file; default `./machines.json`
`MACHINE_STATE_DIR`	no	path to machine state directory; default `./machine_state`
`SLACK_BOT_TOKEN`	no	If using the Slack integration, the Bot User OAuth Token for your installation of the app.
`SLACK_APP_TOKEN`	no	If using the Slack integration, the Socket OAuth Token for your installation of the app.
`SLACK_SIGNING_SECRET`	no	If using the Slack integration, the Signing Secret for your installation of the app.
`SLACK_CONTROL_CHANNEL_ID`	no	If using the Slack integration, the Channel ID of of the private channel for admins to control MAC.
`SLACK_OOPS_CHANNEL_ID`	no	If using the Slack integration, the Channel ID of of the public channel where Oops and maintenance notices will be posted, and where machine status can be checked.

Machine State Directory

During operation, the state of each machine is cached on disk every time it’s updated; this is done to ensure that a restart of the server will not affect running machines. As of this time, state is saved to a separate file for each machine. By default, these are saved in a machine_state subdirectory of the current directory, which is created if it does not exist. An alternate directory to save machine state to can be specified via the MACHINE_STATE_DIR environment variable.