Sensor API

This wiki is deprecated, new documentation here.

Introduction

Material Plane uses a sensor to detect the location of one or more IR bases (or IR pens). This data transmission is done either through a websocket or through the USB port.

Data sent by the sensor

All the data send by the sensor is in JSON format. There are 3 main messages that the sensor sends, which can be identified by the "status" property.

Ping

The sensor will send out a ping message every 500ms, which is used to check if the connection is still alive, and is used to send the status of the battery:

{
  "status": "ping",
  "source": [source (String)],
  "battery": {
    "charging": [charging state (bool)],
    "usbActive": [usb active state (bool)],
    "voltage": [battery voltage (float)],
    "percentage": [battery percentage (float)]
  }
}

• "source" indicates the state of the sensor. When it is performing normally, it will be "mainLoop", but during a calibration procedure it will be "calibration".
• "charging" indicates whether the battery is currently being charged. It will be either 1 (charging) or 0 (not charging)
• "usbActive" indicates whether the usb cable is plugged in. It will be either 1 (plugged in) or 0 (not plugged in)
• "voltage" is the approximate battery voltage (in Volts)
• "percentage" is the approximate charge percentage of the battery

Update

The sensor will send the update command whenever it first connects to the client, and when a settings is changed.

{
  "status": "update",
  "firmware": [firmware version (String)],
  "hardware": [hardware version (String)],
  "ir": {
    "exposure": [exposure time in ms (float, 0.02 - 13)],
    "framePeriod": [frame period in ms (float, 5 - 100)],
    "gain": [gain (float, 1 - 8)],
    "brightness": [minimum brightness (int, 0 - 255)],
    "noise": [noise threshold (int, 0 - 255)],
    "average": [average count (int, 0 - 20)],
    "minArea": [minimum area (int, 0 - 255)],
    "maxArea": [maximum area (int, 0 - 65535],
    "points": [maximum number of detectable points (int, 0 - 16]
  },
  "cal": {
    "mirrorX": [mirror x enabled (bool)],
    "mirrorY": [mirror y enabled (bool)],
    "rotation": [rotation enabled (bool)],
    "offsetX": [offset x value (int, -100 - 100)],
    "offsetY": [offset y value (int, -100 - 100)],
    "calibrationEnable": [calibration enabled (bool)],
    "offsetEnabled": [calibration offset enabled (bool)]
  },
  "sett": {
    "debug": [debug output enabled (bool)],
    "serialOut": [data is output on the serial (USB) port (bool]
  },
  "network": {
    "ssid": [ssid of the network the sensor is connected to (String)],
    "ipAddress": [ip address of the sensor (String)],
    "name": [DNS name of the sensor (String)],
    "wsMode": [mode of the websocket (String, either: "Off", "Client" or "Server")],
    "wsPort": [port of the websocket server (int, 0 - 65535)],
    "wsConnected": [number of connected clients to the websocket server (int)],
    "wsClients": [connected clients' ip addresses (String array)]
  }
}

Data sent to the sensor

When sending data to the sensor, it has to be sent as a string. Most commands follow a simple structure: [SET/GET] [CATEGORY] [VARIABLE] [DATA]
For example, to set the frame period of the sensor to 5ms, you would send: SET IR FRAMEPERIOD 5
GET commands only function when connected using the serial port.

Here is a list of all the commands you can send:

 HELP                                                   - Prints a help message to the serial port with all available commands
 RESTART                                                - Restarts the sensor
 GET STATUS                                             - Prints all settings to the serial port
 SET DEFAULT                                            - Sets all settings to their default values

 SET/GET DEBUG [enable (bool)]	                        - Serial debugging
 SET/GET SERIALOUT [enable (bool)]	                - Outputting data to the serial port

 SCAN WIFI                                              - Scan for nearby WiFi access points
 SET/GET WIFI SSID [name (String)] [password (String)]	- Connects to the access point
 GET WIFI CONNECTED                                     - WiFi connection state
 GET WIFI IP                                            - IP address of the sensor

 SET/GET WIFI NAME [name (String)]	                - DNS name of the server
 SET/GET WS MODE [mode (String)]			- Websocket mode: OFF/CLIENT/SERVER
 SET/GET WS PORT [port (int, 0 - 65535)]		- Websocket port 
 SET/GET WS IP [ip (String)]			        - Websocket IP address (if set to "CLIENT" mode)
 GET WS RUNNING                                         - Websocket running state
 GET WS CLIENTS                                         - Connected clients to the websocket server

 SET/GET IR AVERAGE [average count (int, 0 - 20)]	- Average count
 SET/GET IR FRAMEPERIOD [frameperiod (float, 5 - 100)]	- IR Sensor frame period in ms
 SET/GET IR EXPOSURE [exposure (float, 0.02 - 13)]	- IR sensor exposure in ms
 SET/GET IR GAIN [gain (float, 1 - 89)]			- IR sensor gain
 SET/GET IR BRIGHTNESS [brightness (int, 0 - 255)]	- IR sensor brightness threshold
 SET/GET IR NOISE [noise (int, 0 - 255)]		- IR sensor noise threshold
 SET/GET IR MINAREA [area (int, 0 - 255)]		- IR sensor minimum area
 SET/GET IR MAXAREA [area (int, 0 - 65535)]		- IR sensor maximum area
 SET/GET IR POINTS [points (int, 0 - 16)]		- IR sensor maximum detectable points

 PERFORM CALIBRATION [method (String)]		        - Perform calibration using the selected method (SINGLE/MULTI)
 PERFORM OFFSET [method (String)]		        - Perform offset calibration using the selected method (SINGLE/MULTI)
 SET/GET CAL CALIBRATION [enable (bool)]	        - Calibration enable state
 SET/GET CAL OFFSET [enable (bool)]		        - Calibration offset enable state
 SET/GET CAL MIRRORX [enable (bool)]		        - Mirror X enable state
 SET/GET CAL MIRRORY [enable (bool)]		        - Mirror Y enable state
 SET/GET CAL ROTATION [rotation (bool)]	                - Rotation enable state
 SET/GET CAL OFFSETX [offset (int, -100 - 100)]		- Offset X value
 SET/GET IR OFFSETY [offset (int, -100 - 100)]		- Offset Y value