LiftAuth API Overview
Welcome to LiftAuth! This guide will help you understand our terminology, sequence of events, and provide you with the necessary steps to integrate our system with your robots.
Terminology
Robot
A robot is an autonomous or semi-autonomous machine that interacts with the LiftAuth system to request and manage lift access. Each robot in your fleet must be configured to communicate with your fleet manager and LiftAuth servers.
Fleet Manager
The fleet manager acts as the orchestrator for all lift-related operations. It communicates with both the robots and LiftAuth's API servers to ensure seamless coordination. The fleet manager is responsible for:
- Authenticating with the LiftAuth API using an API token.
- Managing requests and responses between robots and LiftAuth servers.
- Enabling and disabling robot mode for exclusive lobby control.
- Handling any error scenarios that arise during lift operations.
Lobby Servers
Lobby servers provide the backend services to interact with lifts in the lobby. Through our WebSocket APIs, these servers enable the fleet manager to:
- Enable exclusive robot mode for lobby control.
- Call a lift to a specific floor.
- Monitor a lift's status and position.
- Control a lift's doors (e.g., open or close them).
- Disable robot mode to release lobby control.
Lift Lobby
A lift lobby refers to a collection of lifts that operate collaboratively within a building or facility. These lifts are coordinated to efficiently transport passengers between a shared set of floors, optimizing wait times and travel paths by working together as a unified system.
Robot Mode
Robot Mode is the state of the lobby where a lift is reserved exclusively for the use of a single robot. It guarantees that the robot's elevator journey from its initial floor to its target floor will not be interrupted by other passengers or even other robots. Usage of this mode is optional and it is not required to make use of the other APIs.
Robot mode reserves a specific lift for the robot and the robot can only use that lift. If enabled, robot mode will have to be disabled after the robot's journey is complete. There is also a timeout of 30 minutes, beyond which robot mode will be disabled automatically, so please ensure your operations complete within this timeframe.
Sequence of Events
| Step | Action | Description |
|---|---|---|
| 1 | Robot is at Lift Landing, Ready to Enter | The robot is positioned at the lift landing, waiting to enter the lift. |
| 2 | Fleet Manager Connects to LiftAuth Servers | Establishes a WebSocket connection using the API key and lift identifier. |
| 3 | Fleet Manager Enables Robot Mode (optional) | Sends a ROBOT_MODE_ON request to take exclusive control of the lobby operations. |
| 4 | Fleet Manager Sends Request to Summon Lift | Sends a CALL_LIFT request to bring the lift to the robot's current floor. |
| 5 | LiftAuth Acknowledges the Request | LiftAuth acknowledges the request and queues it for processing. The lift’s availability and passenger usage determine timing. |
| 6 | Lift Notifies Fleet Manager | The lift arrives at the robot’s floor and sends a notification to the fleet manager. |
| 7 | Fleet Manager Coordinates Robot Movement | Instructs the robot to proceed with entering the lift. |
| 8 | Door Control | Uses SET_DOOR_OPEN to hold the door open and SET_DOOR_CLOSE after the robot enters. |
| 9 | Fleet Manager Sends Request to Send Lift to Target Floor | Sends a CALL_LIFT request to direct the lift to the robot's destination floor. |
| 10 | Lift Services the Target Floor Request | Processes the request and may stop at intermediate floors for other passengers. |
| 11 | Lift Notifies Fleet Manager of Arrival at Target Floor | Notifies the fleet manager when the lift arrives at the destination floor. |
| 12 | Fleet Manager Coordinates Robot Exit | Reconnects to the robot and instructs it to exit the lift. |
| 13 | Door Control | Uses SET_DOOR_OPEN to ensure the lift door remains open until the robot exits, and SET_DOOR_CLOSE after exiting. |
| 14 | Fleet Manager Disables Robot Mode (if on) | Sends a ROBOT_MODE_OFF request to release exclusive control and return lobby to normal operations. |