DeviceIO API Introduction

Getting started with DeviceIO


What is the DeviceIO IoT Management System?

DeviceIO is a service to help you manage your IoT and embedded devices.

Overview:
Create a DeviceIO product using the DeviceIO web console, specifying a product name, password, version number, and upload a firmware binary.

With a product defined in the web console as above, next add the DeviceIO library to your existing ESP32 or ESP8266 Arduino project and specify the product details. You can now deploy the device and it will be automatically managed with the DeviceIO web console.

Management features include remote device firmware update, remote device rebooting, and device sensor reporting.

The first time the DeviceIO library runs on a device it will contact the DeviceIO service via Wi-Fi to obtain a token. The device will save the token to flash memory, then reboot and re-contact the DeviceIO service to obtain the latest firmware version number, and if a newer version is available it will automatically download and install the new firmware.


Developer setup

Tested platforms:

    ESP8266 Arduino Core v2.7.4
    ESP32 Arduino Core 1.0.4

Prerequisites:

  1. Make sure you have the Arduino IDE installed.
  2. Install the DeviceIO library for Arduino. in your Arduino libraries directory
  3. Restart the Arduino IDE.
  4. NOTE: On ESP8266 the Debug Port must be set to Serial, and the Debug level to any value..

Next steps:

  1. Define a new project in the web console .
  2. Add the DeviceIO library headers to your Arduino project.
  3. Define the DeviceIO library object in your Arduino project.
  4. Set the DeviceIO library object parameters including project name and password.
  5. Compile and upload the new firmware to your device, and manage it on the web console.

Code examples

basic.ino, an example to manage remote firmware updates
#include <DeviceIO.h>
#include <WiFi.h> 

  DeviceIO provisioner;

  const char *ssid = "your-wifi-ssid";
  const char *password = "your-wifi-password";

void setup()
{
  Serial.begin(115200);
  Serial.print("Connecting");
  
  // initialize wireless connection
  WiFi.begin(ssid, password);

  // wait for connection to complete
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(250);
    Serial.print(".");
  }

  Serial.println("");
  Serial.print("Connected to ");
  Serial.println(ssid);
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());

  // provision this device automatically
  provisioner.initialize();
  provisioner.debugSerial = 1;
  provisioner.buildNumber = 1;
  provisioner.productIDname ="basic";
  provisioner.productIDpassword ="********";
}

void loop() 
{
  // DeviceIO reporting check-in (OTA, sensors, etc)
  provisioner.doCheckIn();
}					
					

unprovision.ino, unprovisions a device for other uses
#include <DeviceIO.h>
#include <WiFi.h>

  DeviceIO provisioner;

void setup()
{
  Serial.begin(115200);

  // unprovision this device
  provisioner.debugSerial = 1;
  provisioner.initialize();
  provisioner.unprovisionDevice();
}

void loop() 
{

}
					

API documentation


initialize()

[function] Readies the flash file system and reads an existing token from flash memory. Function does not return a value.

doCheckIn()

[Function] Checks in with the DeviceIO server by default every four hours, if the time is not yet elapsed the function will return without doing anything. If the time is elapsed: Automatically obtains a token to identify the device, and reboots after first obtaining it. Reads the remote firmware version number, and if it is higher than the existing device build number, the new firmware binary will automatically be downloaded and installed. If no firmware is updated, reporting of 3 sensor values follows, VCC on ESP8266, Wi-Fi signal strength on both ESP models, and internal temperature sensor on ESP32.

For the provisioning and firmware upgrade features to work, the device 'Partition Scheme' (ESP32) or 'Flash Size' setting (ESP8266) must be properly set in the Arduino IDE. This setting can be found in the 'Tools' pulldown menu option, where the ideal setting is (ESP32) 'Minimal SPIFFS (Large APPS with OTA)' or (ESP8266) '4MB (FS:2MB OTA:~1019KB)'.

Function returns 1 if successful, 0 on failure.

addSensorValue(int sensorNumber, float sensorValue)

[Function] Adds a sensor report to the internal array to be sent at next Check in. The internal array size is 20 and is automatically managed. sensornumber variable should be a positive integer with a value from 1 to 254. Value 255 is reserved for device VCC (or battery) and is provided by default on ESP8266. Value 256 is reserved for WiFi signal strength on both ESP32 and ESP8266. Value 257 is reserved for the temperature sensor on the ESP32. sensorValue is a floating-point variable and can be positive or negative. Function does not return a value.

Sensor data can be remotely retrieved in Json format from the browser or from the command line with the popular tool 'wget'. Product and password with an optional date stamp for start and ending searches returns a standard Json object that can be incorporated into tables or a larger project.

URL Format:
https://deviceio.goodprototyping.com/getjsonsensors?prodID=productidname&prodIDpass=pass123&startdate=2021-01-01&enddate=2021-01-04

unprovisionDevice()

[Function] Erases an existing token from the flash file system. Function does not return a value.

debugSerial

[Variable, uint8_t] 0=off, 1=on. Toggles the display of debugging messages, helpful in diagnosing communication problems. Must be enabled before calling initialize().

buildNumber

[Variable, unsigned long] Sets the current version number, to compare against future version numbers.

productIDname

[Variable, String] Sets the product name. It must be the same as defined in the web console. Maximum editable length is 11, with a pre-defined user prefix of maximum 5 characters, for a total of 16 characters.

productIDpassword

[Variable, String] Sets the product password. It must be the same as defined in the web console. Minimum 8 characters, maximum 16.

checkinInterval

[Variable, unsigned long] Sets the time in milliseconds between each check-in with the DeviceIO server. The default value is four hours (((60*60) * 1000) * 4) = 14400000.

Error Codes

The following error codes are reported by the DeviceIO library:
HTTP Code HTTP Text Meaning
507 Insufficient Storage User restrictions
505 HTTP Version Not Supported No HTTPS
455 DB Update Failed Sensor data db update failed
428 Precondition Required Product name missing or invalid
426 Upgrade Required Token missing or invalid
423 Locked (WebDAV) Password missing or invalid
422 Unprocessable Entity No Command
409 Conflict Sensor data missing or invalid

Note: Error 426 indicates an invalid or missing device token. This would occur if a token was deleted on the devices page, and then a device attempted to log in using this deleted token. In this circumstance the device can be unprovisioned using the example script (get new token), or firmware reinstalled with full flash erase (get new token), or if you cannot access the device contact support to add the token (restore deleted token)