Try it out
Walk Through a Real-World Workflow
Connect to a Lift
We have set up a test lift for you to try out the API before integrating with your own lift. Follow these steps to establish a connection using wscat, a simple WebSocket client for testing:
1. Install wscat
If you don’t already have wscat installed, you can install it globally using npm:
npm install -g wscat
2. Connect to the Test Lift
You can connect to a virtual version of any lift by setting the testing parameter to true
Use the following command to establish a WebSocket connection to our test lift. Replace <API_KEY> with your provided API key and <LIFT_ID> with the test lift ID (TEST_LIFT). For this demo we will connect to our test lift using
Lift ID: lift1
API Key: key1
We are going to add the testing parameter to connect to a virtual instance instead.
wscat -c "wss://webserver-539540931078.asia-east1.run.app/?key=key1&liftId=lift1&testing=true"
3. Send Commands
Once connected, we can send some commands.
Get Lift Position
Before calling the lift we need to know if the lift is already here.
The lift will fulfill all requests on a best effort basis, meaning it might not be fulfilled immediately.
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req001", "command": "GET_LIFT_POSITION" }
Assuming the lift is already stationary at the same floor as the robot, we can proceed to enter.
Open the Door
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req002", "command": "SET_DOOR_OPEN" }
Drive Robot In
This is the stage where you drive the robot into the lift.
Close the Door
Once the robot was in the lift, we can close the door.
Sending the close door request does not close the door immediately. It releases door control back to the lift so the lift system can close the door naturally.
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req003", "command": "SET_DOOR_CLOSE" }
Send the lift to Floor 1
Once the door is closed, send a request for the lift to travel to that floor.
The lift might not service that floor immediately. It will visit intermediate floors especially if the lift is being shared by human passengers.
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req004", "command": "CALL_LIFT", "parameters": { "targetFloor": 1 }}
When the lift arrives at a floor, it broadcasts a message to the websocket. Wait until it arrives at your target floor.
Cheat Code
And that's it! You have used all the basic commands required for you to control the lift. Now, we will show you how to create a basic script below that allows you to broadcast and listen to the responses before moving on to the next page.
Setting Up npm and Dependencies
Before running the JavaScript file, ensure you have Node.js and npm installed on your system. Follow these steps to set up the required environment:
1. Install Node.js and npm
Download and install Node.js, which includes npm, from the official Node.js website. Follow the installation instructions for your operating system.
2. Initialize a New npm Project
Navigate to your project directory and initialize a new npm project:
mkdir lift-control
cd lift-control
npm init -y
3. Install Required Dependencies
Install the ws package, which is a WebSocket client for Node.js:
npm install ws
4. Save the JavaScript File
Create a new file named lift-control.js in your project directory and copy the following script into it:
const WebSocket = require("ws");
// Replace these with your API Key and Lift ID
const apiKey = "key1";
const liftId = "lift1";
const testing = "true"; // Enables virtual instance for testing
const wsUrl = `<WEBSOCKET_ENDPOINT>?key=${apiKey}&liftId=${liftId}&testing=${testing}`;
const socket = new WebSocket(wsUrl);
// Store the current step in the workflow
let currentStep = 0;
socket.onopen = () => {
console.log("Connected to WebSocket server.");
runNextStep();
};
socket.onmessage = (event) => {
const response = JSON.parse(event.data);
console.log("Received response:", response);
// Handle responses and move to the next step based on the current step
if (currentStep === 1 && response.command === "GET_LIFT_POSITION") {
console.log("Lift position retrieved.");
currentStep++;
runNextStep();
} else if (currentStep === 2 && response.command === "SET_DOOR_OPEN") {
console.log("Door opened.");
currentStep++;
runNextStep();
} else if (currentStep === 3) {
console.log("Drive robot into the lift.");
currentStep++;
runNextStep();
} else if (currentStep === 4 && response.command === "SET_DOOR_CLOSE") {
console.log("Door closed.");
currentStep++;
runNextStep();
} else if (currentStep === 5 && response.command === "CALL_LIFT") {
if (
response.status === "arrived" &&
response.parameters.targetFloor === 1
) {
console.log("Lift arrived at floor 1.");
socket.close();
}
}
};
socket.onclose = () => {
console.log("WebSocket connection closed.");
};
socket.onerror = (error) => {
console.error("WebSocket error:", error);
};
// Function to send a command to the WebSocket server
const sendCommand = (command) => {
console.log("Sending command:", command);
socket.send(JSON.stringify(command));
};
// Function to handle each step in the workflow
const runNextStep = () => {
switch (currentStep) {
case 0:
console.log("Step 1: Get Lift Position.");
sendCommand({
requestId: "req001",
command: "GET_LIFT_POSITION",
});
currentStep++;
break;
case 1:
console.log("Step 2: Open the Door.");
sendCommand({
requestId: "req002",
command: "SET_DOOR_OPEN",
});
currentStep++;
break;
case 2:
console.log("Step 3: Drive Robot Into the Lift.");
// Simulate robot entering the lift (manual intervention in real-world use).
setTimeout(() => {
console.log("Robot has entered the lift.");
runNextStep();
}, 5000); // Wait 5 seconds to simulate robot movement
break;
case 3:
console.log("Step 4: Close the Door.");
sendCommand({
requestId: "req003",
command: "SET_DOOR_CLOSE",
});
currentStep++;
break;
case 4:
console.log("Step 5: Send Lift to Floor 1.");
sendCommand({
requestId: "req004",
command: "CALL_LIFT",
parameters: {
targetFloor: 1,
},
});
currentStep++;
break;
default:
console.log("Workflow complete.");
break;
}
};
5. Run the Script
Execute the script using Node.js:
node lift-control.js
Follow the console output to see the workflow in action.