This document is relevant only for the following hardware:
Mirobot uses standard data formats and protocols to enable it to be controlled from any programming language, including directly from the browser. Here’s how it works…
All communication with Mirobot is done by sending and receiving JSON packets over a WebSocket. Because Mirobot is asynchronous (i.e. it doesn’t execute a command immediately) there can be multiple responses to a message that is sent. It can also broadcast notifications for events such as bumping into an obstacle. The JSON message from the client to Mirobot has three parameters:
A response from Mirobot has the following parameter:
For example:
{"cmd":"forward", "arg":100, "id":"abc123"}
will tell Mirobot to move forward by 100mm. When this is sent, Mirobot will immediately respond with a message saying that this command has been accepted:
{"status":"accepted", "id":"abc123"}
and once the command has completed, another response will be transmitted
{"status":"complete", "id":"abc123"}
There are two types of commands that can be sent to Mirobot”
Short commands can be sent at any time, regardless of other commands being sent. If you try to send a long command before another long command has completed you will receive an error response:
{"status":"error", "msg":"Previous command not finished", "id":"abc321"}
Other errors include sending a command which is not recognised:
{"status":"error", "msg":"Command not recognised", "id":"abc321"}
or sending badly formed JSON:
{"status":"error", "msg":"JSON parse error", "id":"abc321"}
If you enable notifications for a particular event you will receive occasional messages when the event happens. For example, if you enable notifications for collision, you will receive notification messages which look like this:
{"status":"notify", "msg":"left", "id":"collide"}
Because this notification is not in response to a particular message that you sent, the id is set to the id of the event that occurred, in this case “collide”.
Quick reference:
| Command | Argument | Type |
|---|---|---|
| version | none | short |
| ping | none | short |
| uptime | none | short |
| pause | none | short |
| resume | none | short |
| stop | none | short |
| forward | mm to move | long |
| back | mm to move | long |
| right | degrees to turn | long |
| left | degrees to turn | long |
| penup | none | long |
| pendown | none | long |
| beep | milliseconds to beep for | long |
| collide | a floating point scaling factor | short |
| collideState | none | short |
| collideNotify | true/false | short |
| follow | none | short |
| followState | none | short |
| followNotify | true/false | short |
| slackCalibration | none | short |
| calibrateSlack | the number of steps for the calibration | short |
| moveCalibration | none | short |
| calibrateMove | a floating point scaling factor | short |
| turnCalibration | none | short |
| calibrateTurn | a floating point scaling factor | short |
Used to determine which version of the firmware is running. The msg parameter of the response contains the version string.
{"cmd":"version", "id":"54321"}
response:
{"status":"complete", "msg":"2.0.10", "id":"54321"}
Used to make sure the communications are still active. No side effects.
{"cmd":"ping", "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Used to check how long the Arduino has been running since boot. Returns the number of milliseconds as the message.
{"cmd":"uptime", "id":"54321"}
response:
{"status":"complete", "msg":"12643", "id":"54321"}
Pauses the currently operating command.
{"cmd":"pause", "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Resumes a paused command.
{"cmd":"resume", "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Stops the current command.
{"cmd":"stop", "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Moves Mirobot forward by the specified amount of mm
{"cmd":"forward", "msg":100, "id":"54321"}
response:
{"status":"accepted", "id":"54321"}
{"status":"complete", "id":"54321"}
Moves Mirobot back by the specified amount of mm
{"cmd":"back", "msg":100, "id":"54321"}
response:
{"status":"accepted", "id":"54321"}
{"status":"complete", "id":"54321"}
Turns Mirobot right by the specified amount of degrees
{"cmd":"right", "msg":90, "id":"54321"}
response:
{"status":"accepted", "id":"54321"}
{"status":"complete", "id":"54321"}
Turns Mirobot left by the specified amount of degrees
{"cmd":"left", "msg":90, "id":"54321"}
response:
{"status":"accepted", "id":"54321"}
{"status":"complete", "id":"54321"}
Moves the pen arm into the up position
{"cmd":"penup", "id":"54321"}
response:
{"status":"accepted", "id":"54321"}
{"status":"complete", "id":"54321"}
Moves the pen arm into the down position
{"cmd":"pendown", "id":"54321"}
response:
{"status":"accepted", "id":"54321"}
{"status":"complete", "id":"54321"}
Enables built-in collision detection. To stop, send the “stop” command.
{"cmd":"collide", "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Returns the state of the collision sensors. Can be either “none”, “left”, “right” or “both” depending on the state of the sensors.
{"cmd":"collideState", "id":"54321"}
response:
{"status":"complete", "msg":"left", "id":"54321"}
Enables or disables collision notifications by sending either true or false as the argument.
{"cmd":"collideNotify", "arg":true, "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Once enabled, notifications will be emitted when the relevant events happen, e.g.
{"status":"notify", "msg":"left", "id":"collide"}
Enables built-in line following. To stop, send the “stop” command.
{"cmd":"follow", "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Returns the state of the line follower sensors. This is a number that represents the difference in analogue readings for each sensor. When negative it means that the left sensor is over white and the right is over black and the opposite for positive.
{"cmd":"followState", "id":"54321"}
response:
{"status":"complete", "msg":-62, "id":"54321"}
Enables or disables line follower notifications by sending either true or false as the argument.
{"cmd":"followNotify", "arg":true, "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Once enabled, notifications will be emitted when the value as described above changes. This can result in quite a lot of messages and this is quite normal.
{"status":"notify", "msg":-63, "id":"follow"}
Returns the number of steps that Mirobot moves to pick up the slack in the gearing mechanism of the stepper motors.
{"cmd":"slackCalibration", "id":"54321"}
response:
{"status":"complete", "msg":12, "id":"54321"}
Sets the number of steps that Mirobot moves to pick up the slack in the gearing mechanism of the stepper motors. This also puts it into a mode which tests the calibration by moving backwards and forwards by the amount specified. To stop this send the “stop” command.
{"cmd":"slackCalibration", "arg":12, "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Returns the scaling factor that Mirobot applies to every move. This is also applied to the turning movements.
{"cmd":"moveCalibration", "id":"54321"}
response:
{"status":"complete", "msg":0.997, "id":"54321"}
Sets the scaling factor that Mirobot applies to every move. This is also applied to the turning movements.
{"cmd":"slackCalibration", "arg":0.997, "id":"54321"}
response:
{"status":"complete", "id":"54321"}
Returns the scaling factor that Mirobot applies to every turn. This is applied after the move calibration has been applied.
{"cmd":"turnCalibration", "id":"54321"}
response:
{"status":"complete", "msg":0.997, "id":"54321"}
Sets the scaling factor that Mirobot applies to every turn. This is applied after the move calibration has been applied.
{"cmd":"turnCalibration", "arg":0.997, "id":"54321"}
response:
{"status":"complete", "id":"54321"}