API Information
All devices in the Access Control system can communicate back to the central Access Control Server/Database through JSON-based REST API messages. The following messages are used by the Access Control Hardware. Due to processing limitations, the Access Control Hardware must always initiate communication, it is not possible for the Server to ping devices or ask for data or provide state updates.
Unless otherwise stated, all data is assumed Strings up to 32 characters long comprised of alphanumeric (0-9, a-z, A-Z) or some special ($ - _ . + ! * ' ( ) ,) characters. When used in a GET query, they are all forced lowercase. When used in a JSON document, they are treated as case sensitive, but there are no guarantees they will be fully processed case sensitive.
The Welcome message is the only message type sent by the Sign-In Reader. It is used to indicate to the Server that user [UID] has signed in to the area [Zone]. This is used both for analytics, as well as to give the option that a user must sign in to the lab before using a machine. A 0 or 1 is sent back to the Sign In Reader to indicate to it if the ID exists in the database. This is then used to beep a confirmation/denial, letting the user know it is OK to proceed.
PUT to example.com/api/welcome
JSON Document
- Type: Welcome
- Zone: [Zone]
- ID: [UID]
- Key: [Key]
- HTTP 406 if user is not in system
- HTTP 202 if user is in system
- else will retry
- [Zone] is the name for the area that the machine is deployed in.
- [Key] is a unique API access key. Without a valid API key, a 403 is returned.
- [UID] is a 14 char String (AABBCCDDEEFFGG). It is the MiFare/ISO UID represented in hexadecimal.
Authorization is the most important message type. This is used by the Core to check if a user is permitted to use their machine.
GET from example.com/api/auth?type=[MachineType]&machine=[MachineID]&zone=[Zone]&needswelcome=[NeedsWelcome]&id=[UID]
JSON Document
- Type: Authorization
- Machine: [MachineID]
- UID: [UID]
- Allowed: [Allowed]
- [MachineType] is a String representing the machine's type (non-exclusive), used for determining permission to use.
- [MachineID] is the unique machine identifier.
- [Zone] is the name for the area that the machine is deployed in.
- [NeedsWelcome] is a bool, representing that this machine can only be accessed if the user has signed in first. 1 for yes, 0 for no.
- [UID] is a 14 char String (AABBCCDDEEFFGG). It is the MiFare/ISO UID represented in hexadecimal.
- [Allowed] is a bool, representing if a user is permitted to use that machine. 1 for yes, 0 for no.
Status is a standard message sent periodically by the Cores when they are online, to tell the Server of their state. These messages are sent on a set time interval, as well as automatically on important events (machine coming online, session starting/ending, override state change, etc.). The frequency of messages being sent is defined in the device's configuration EEPROM.
PUT to example.com/api/status/[MachineID]
JSON Document
- Type: Status
- Machine: [MachineID]
- MachineType: [MachineType]
- Zone: [Zone]
- FEVer: [FrontEnd]
- BEVer: [BackEnd]
- HWVer: [Hardware]
- Temp: [Temperature]
- State: [State]
- UID: [StateUID]
- Time: [SessionTime]
- Help: [HelpState]
- Source: [Source]
- Frequency: [Frequency]
- Key: [Key]
- HTTP 200
- Else will retry
- [MachineID] is the unique machine identifier.
- [MachineType] is a String representing the machine's type (non-exclusive), used for determining permission to use.
- [Zone] is the name for the area that the machine is deployed in.
- [FrontEnd] is the firmware version of the frontend. It is only updated on startup, but reported in every message.
- [BackEnd] is the firmware version of the backend. It is only checked on startup, but reported in every message.
- [Hardware] is the revision of the hardware. Since this is stored as a value on the ESP32's EEPROM, it is not always 100% reliable.
- [Temperature] is the highest temperature from any sensors in an Access Control system. It is a String with 2 decimals of precision (XX.XX) and no trailing or leading zeros. Numbers below 0 are sent as just 0.
- [State] is the current state of a machine. Options are;
- Idle: Machine is in normal mode and no session is active.
- Active: Machine is in normal mode and a session is active.
- Lockout: Machine is in a lockout state.
- AlwaysOn: Machine has been set to be always on.
- [StateUID] is formatted the same as [UID]. When the machine is Active, it will show the UID of the current user. If the machine is Idle, AlwaysOn, or Lockout, it will show the UID of the last user. If the machine has not yet had a user, it will return all 0s.
- [SessionTime] can represent different things. If there is an ongoing session, it will return how long that session has been going on for. If there is no active session, it will return the length of the last session. If the machine is in Lockout or Always On, it will return how long it has been in that state for.
- [Source] is the reason for a status message to be sent. Options are;
- Scheduled: The normal amount of time has elapsed between messages
- SessionStart: A new session has been started.
- SessionEnd: A session has ended.
- StateChange: The system has had its state overidden to/from AlwaysOn or Lockout (usually means someone flipped the switch, but could also be an internal error has forced the system into Lockout).
- Startup: The system has just powered on.
- Temperature: The system has exceeded an internally-defined temperature warning on one of its sensors. This message is only sent once as it exceeds the threshold, however a machine may have multiple thresholds (e.g. a "warning" threshold, and a "shutdown" threshold). The message for this threshold is not sent again unless the system drops below the threshold, or is power-cycled.
- Error: Sent after a Message to provide information on the system to help in debugging.
- [Help] is a 0 or 1, representing if the machine is currently asking for help. This is used to catch desyncs between the device and the website when a /help message maybe gets lost.
- [Frequency] is how often a system is supposed to send status messages, in whole-number seconds.
- [Key] is a unique API access key. Without a valid API key, a 403 is returned.
Help is used to let the server know that a user has pressed the help button on their machine. This is also sent to end the help request.
PUT to example.com/api/help
JSON Document:
- Type: Help
- Machine: [MachineID]
- Zone: [Zone]
- Key: [Key]
- HTTP 200
- Else will retry
- [MachineID] is the unique machine identifier.
- [Zone] is the area/room that a machine is deployed in
- [Key] is a unique API access key. Without a valid API key, a 403 is returned.
Message is a rarely-used message type, that allows the device to send plaintext reports to the Server. These are mostly used for debugging and to report unexpected errors/states.
GET from example.com/api/message/[MachineID]?message=[Message]
- HTTP 200
- Else will retry
- [MachineID] is the unique machine identifier.
- [Message] is a String of unknown length, containing a plaintext error message that should be logged to be investigated as a bug.
Check is a simple message type, used by Access Control Hardware to check that it still has a connection to the Server periodically. This message type is not sent if other recent calls returned correctly. So, it is really only used if the Status messages are turned off or set to a very low interval. Since the MachineID is included in the GET, the Server is aware of what machines are online currently.
GET from example.com/api/check/[MachineID]
- HTTP 200
- Else assume fail
- [MachineID] is the unique machine identifier.
State is used to check the last returned state of a machine from a Status update. This is most often used by secondary devices to provide non-time-sensitive secondary actions (e.g. warning "machine is on" lights, automated blast gates that open when a machine is on, etc.).
GET from example.com/api/state/[MachineID]
JSON Document
- Type: State
- Machine: [MachineID]
- State: [State]
- [MachineID] is the unique machine identifier.
- [State] is the current state of a machine. Options are;
- Idle: Machine is in normal mode and no session is active.
- Active: Machine is in normal mode and a session is active.
- Lockout: Machine is in a lockout state.
- AlwaysOn: Machine has been set to be always on.
- [Key] is a unique API access key. Without a valid API key, a 403 is returned.
Batch is similar to State, but more efficient for devices that need to know the state of multiple machines. This is used by secondary devices providing non-time-sensitive secondary actions that apply to a large group of machines (e.g. turning on the dust collector for a room when any machine in there is on, a status panel showing the state of machines in a Zone, etc.). There is no upper/lower limit on the number of machines that can be requested at once, except for the longest URL length the Core can process (around 1000 characters).
GET from example.com/api/batch?&machine1=[MachineID]&machine2=[MachineID]&machine3=[MachineID]...
JSON Document
- Type: Batch
- MachineID: [State]
- MachineID: [State]
- MachineID: [State]
- ...
- [MachineID] is the unique machine identifier.
- [State] is the current state of a machine. Options are;
- Idle: Machine is in normal mode and no session is active.
- Active: Machine is in normal mode and a session is active.
- Lockout: Machine is in a lockout state.
- AlwaysOn: Machine has been set to be always on.
- [Key] is a unique API access key. Without a valid API key, a 403 is returned.
