Overview
This page describes the low-level serial APIs used to manage UbiBot devices such as WS1 and WS1 Pro model. There are currently two ways to access the APIs:
- USB serial port
Please note the following when connecting to your device:
- Use the supplied Micro-USB cable or a compatible cable with four wires inside (positive, negative, data transfer & data receive). Some cheap cables only offer charging.
- Switch off the device before connecting it to the PC using the Micro-USB cable.
- Make sure the correct USB serial port is selected and turned on for connection.
- Serial port settings:
- Baudrate: 115200
- Data bits: 8
- Parity: none
- Stop Bits: 1
- Receive & Send: Text format
Serial APIs for Reading Information About the Device
The following APIs read information from the connected device.
Read device firmware information
This returns details of the firmware version, channel ID, user ID and serial number of the device.
Request:
{"command":"ReadProduct"}
Response：
{"ProductID":"ubibot-ws1-cn","SeriesNumber":"XXXXXX","Host":"webapi.ubibot.com","CHANNEL_ID":"XX","USER_ID":"XXX-XXXX","USAGE":"0%","firmware":"ws1_v1.6_17_10_18","backup_ip":"xxx.xxx.xxx.xxx"}
Read device WiFi configuration
This returns the SSID and password of the Wi-Fi access point the device is configured to use.
Request：
{"command":"ReadWifi"}
Response：
{"SSID":"XXXXXX","password":"XXXXXX","type":"WPA"}
Read device sensor configuration (metadata)
This returns the SSID and password of the Wi-Fi access point the device is configured to use.
Request:
{"command":"ReadMetaData"}
Response：
{"fn_th":120,"fn_light":60,"fn_mag":86400,"fn_mag_int":2,"fn_acc_tap1":0,"fn_acc_tap2":0,"fn_acc_act":0,"fn_acc_min":90,"fn_bt":300,"fn_ext":600,"fn_battery":36
00,"fn_dp":600,"cg_data_led":1}
Read stored sensor data from device
This returns the sensor data that is stored on the device. The WS1 can hold over 300,000 sensor readings.
Request:
{"command":"ReadData"}
Response：
{"created_at":"2015-12-17T18:16:22Z","field1":0}……
Read error log
Request：
{"command":"GetLastError"}
Scan nearby WiFi access points
This returns the sensor data that is stored on the device. The WS1 can hold over 300,000 sensor readings.
Request：
{"command":"ScanWifiList"}
Response：
{"WiFi_List_Sum":%d }\n\r
{"SSID":"%s","rssi":%d,"type":%d}\n\r
Run device diagnostics test
This command triggers the device to read all the sensors and return the results.
Request：
{"command":"CheckSensors"}
Response：
{"created_at":"2017-05-12T04:41:10Z","temp_val":32.132446,"humi_val":17,"light_val":767.359985,"power_vol_val":4.524133,"ssid":"m_work-GN","rssi":-37,"acce_xval":0,"acce_yval":0,"acce_zval":0,"mag_val":1,"ext_temp_val":65535}
Serial APIs for Making Changes to the Device (Make sure you have backed up all the data)
The following commands are used to change the device settings. Please make sure you have backed up or synced all data before running these commands.
Delete all stored data
This command deletes the data stored internally on the device. It can take up to 30 seconds to run.
NB the data is deleted permanently.
Request：
{"command":"ClearData"}
Change device sensor configuration
This command is used to change the sensor metadata.
NB the new metadata sent with the request must be supplied in JSON format as show in the example.
Request：
{"command":"SetMetaData","metadata":"{\"fn_th\":60,\"fn_light\":60,\"fn_mag\":120,\"fn_mag_int\":2,\"fn_acc_tap1\":0,\"fn_acc_tap2\":0,\"fn_acc_act\":0,\"fn_acc_min\":5,\"fn_bt\":120,\"fn_ext_t\":1480041854,\"fn_battery\":120,\"fn_dp\":120,\"cg_data_led\":\"on\"}"}
Response (if successful)：
{\"status\":0,\"code\": 0x00}
Change WiFi configuration
This command updates the Wi-Fi configuration of the device. It takes the following parameters:
SSID: SSID of the new Wi-Fi access point
Password: The password for the access point (plain text)
Type: WPA, WEP or OPEN
Backup IP: IP address to use if DNS isn’t working
Request：
{"command":"SetupWifi","SSID":"XXXXX","password": "XXXXX","backup_ip":"101.201.30.5","type":"wpa"}
Response if successful：
{\"status\":0,\"code\": 0x00}
Change device host endpoint address
If you’re interested in configuring UbiBot devices to connect to your own private server or platform, please join the UbiBot Developer program. Membership includes the following benefits and resources:
- UbiBot device and server communication API documents
- UbiBot server-side quick-start SDK (PHP): demo code showing how device activation and data sync processes are carried out.
- User guide for building a private IoT platform utilising UbiBot devices.
- Access to UbiBot Beta Devices
- Access to UbiBot Beta Releases
- Advanced API capabilities
- Development support
- Partner with us
