IoTool Arduino library documentation

IoTool Arduino library

This library allows an Arduino to communicate with the IoTool application. Data is sent and received using a Bluetooth connection. IoTool supports classic Bluetooth modules and the integrated Bluetooth Low Energy on Arduino/Genuino 101. Follow the first part of the IoTool Arduino extension user guide to get it working.

Examples

Sensor
Action
Actions and sensors combined
Arduino/Genuino 101 Bluetooth Low Energy

Functions

IoTool
- IoTool
- setSerial()
- setBleSerial()
- addSensor()
- addAction()
- loop()
IoToolSensor
- write()
IoToolAction
- setHandler()
CurieBLESerial
- begin()

IoTool constructor

Description

IoTool is the base class of the IoTool library. It holds all set sensors and actions, the Stream object and is responsible for sync and action execution handling.

Syntax

IoTool ioTool()

Example

#include <IoTool.h>

/* Initialize IoTool object */
IoTool ioTool;

void setup() {
}

void loop() {
}

setSerial()

Description

Sets the serial connection that will be used to send and receive data from the IoTool Arduino service.

Syntax

ioTool.setSerial(stream)

Parameters

ioTool: IoTool object
stream: Stream object

Example

#include <IoTool.h>

IoTool ioTool;

void setup() {
  /* In this example Serial is used as a stream object */
  /* Initialize Serial connection before setting it to the IoTool object */
  Serial.begin(9600);
  ioTool.setSerial(Serial);
}

void loop() {
}

setBleSerial()

Desctiption

Sets an emulated serial connection on Arduino/Genuino 101 as a communication channel between 101 and IoTool Arduino service. Use this only with built in Bluetooth LE on Arduino/Genuino 101.

Syntax

ioTool.setBleSerial(bleSerial)

Parameters

bleSerial: CurrieBLESerial object

Example

/* WARNING: This is only implemented on Arduino/Genuino 101 */
#include <IoTool.h>

IoTool ioTool;
CurrieBLESerial cSerial;

void setup() {
  /* Initialize 101 BLE Serial emulation */
  cSerial.begin();

  /* Attach CurrieBLESerial object to the IoTool object */
  ioTool.setBleSerial(cSerial);
}

void loop() {
}

addSensor()

Description

Adds a sensor to the IoTool object. Adding a sensor to the IoTool object enables it to be detected by the Sync function in the IoTool Arduino service.

Syntax

ioTool.addSensor(sensor)

Parameters

ioTool: IoTool object
sensor: IoToolSensor object

Example

#include <IoTool.h>

/* Initialize IoTool object */
IoTool ioTool;

/* Initialize IoToolSensor object with id, name, and short name */
IoToolSensor sensor("id", "Sensor name", "S.Name");

void setup() {
  /* Add sensor to the IoTool object */
  ioTool.addSensor(sensor);
}

void loop() {
}

addAction()

Description

Adds an action to the IoTool object. Adding an action to the IoTool object enables the action to be detected by the Sync function in the IoTool Arduino service.

Syntax

ioTool.addAction(action)

Parameters

ioTool: IoTool object
action: IoToolAction object

Example

#include <IoTool.h>

IoTool ioTool;

/* Initialize action using id, name constructor */
IoToolAction action("id", "name");

void setup() {
  /* Add action to IoTool object, this action will now be visible in IoTool after sync. */
  ioTool.addAction(action);
}

void loop() {
}

loop()

Description

The main processing loop of the IoTool object. This should not be blocked with delay() calls, as it may result in potentially unexecuted actions.

Syntax

ioTool.loop()

Parameters

ioTool: IoTool object

Example

#include <IoTool.h>

IoTool ioTool;

void setup() {
  /* At minimum, Stream object such as Serial should be provided to use loop() method */
  Serial.begin(9600);
  ioTool.setSerial(Serial);
}

void loop() {
  /* Do not block this loop with delay() calls, as this will result in unexecuted actions */
  ioTool.loop();
}

IoToolSensor constructor

Description

A constructor for creating sensor objects.

Syntax

sensor(id, name, shortName)
sensor(id, name, shortName, units)
sensor(id, name, shortName, decimalPlaces)

Parameters

sensor: IoToolSensor object variable name
id: sensor id (must be unique)
name: sensor name
shortName: short sensor name displayed in IoTool dashboard (up to ~8 characters)
units: sensor data units
decimalPlaces: number of decimal places to use in IoTool dashboard

Example

#include <IoTool.h>

IoTool ioTool;

/* First constructor id, name, short name */
IoToolSensor sensor("id", "My sensor", "M.sens");

/* Second constructor id, name, short name, units */
IoToolSensor tempSensor("t", "Temperature", "Temp", "C");

/* Third constructor id, name, short name, units, decimal places */
IoToolSensor acc("acc", "Acceleration", "Acc", "G", 2);

void setup() {
}

void loop() {
}

write()

Description

The write method sends a provided numeric value to the IoTool app. The value is sent immediately.

Syntax

sensor.write(value)

Parameters

sensor: IoToolSensor object
value: Numeric value (byte, char, int, long, float, double)

Example

#include <IoTool.h>

/* Create IoTool object */
IoTool ioTool;

/* Create sensor object*/
IoToolSensor sensor("id", "Sensor", "Sens");

/* Time keeping variable */
unsigned long pMillis;

void setup() {
  /* Initialize Serial connection */
  Serial.begin(9600);

  /* Set Serial connection, IoTool will use this connection to communicate with IoTool App */
  ioTool.setSerial(Serial);

  /* Add sensor to the IoTool object */
  ioTool.addSensor(sensor);
}

void loop() {
  /* Call main loop of the ioTool object, this is neccesary to enable Sync functionality */
  ioTool.loop();

  /**
   * Delay should not be used, as it will block executon of IoTool loop.
   * Use millis() instead, check if difference in time is equal or greater
   * than 500 ms, if it is wirte value to the sensor and update time keeping
   * variable
   */
  if (millis() - millis >= 500) {
    /* Update time keeping variable */
    pMillis = millis();

    /* Write value of the Analog Pin 0 to the sensor */
    sensor.write(analogRead(0));
  }
}

IoToolAction constructor

Description

Creates an IoToolAction object.

Syntax

action(id, name);

===Parameters * action: IoToolAction object variable name * id: unique id of the action * name: name of the action, this value will be displayed in the IoTool app

Example

#include <IoTool.h>

IoTool ioTool;

IoToolAction action("id", "My action");

void setup() {
}

void loop() {
}

setHandler()

Description

Set callback function for an IoToolAction object. This function will be executed in the IoTool loop() method when given the signal to execute. The method accepts a function with the following signature: void /functionname/(void).

Syntax

action.setHandler(handler)

Paramaters

action: IoToolAction object
handler: function pointer

Example

#include <IoTool.h>

IoTool ioTool;

IoToolAction action("id", "Toggle LED");

/* Action handler function */
void actionHandler() {
  /* Toggle LED on pin 13 */
  digitalWrite(13, !digitalRead(13));
}

void setup() {
  /* Set pin 13 as output */
  pinMode(13, OUTPUT);

  /* Initialize Serial object and set it to the IoTool object */
  Serial.begin(9600);
  ioTool.setSerial(Serial);

  /* Add action handler function to the IoToolAction object */
  action.setHandler(actionHandler);
}

void loop() {
  /* Action will be executed here when given signal from IoTool app */
  ioTool.loop();
}

CurieBLESerial constructor

Desctiption

The CurieBLESerial object emulates a LE connection as a Stream object, allowing Bluetooth LE on Arduino/Genuino 101 to be used with IoToolLibrary in same way as a normal Serial object.

Syntax

CurieBLESerial cSerial

Parameters

cSerial: CurieBLESerial object variable name

Example

/* WARNING: This is only implemented on Arduino/Genuino 101 */
#include <IoTool.h>

/* Initialize CurrieBLESerial object */
CurieBLESerial cSerial;

void setup() {
}

void loop() {
}

begin()

Description

The begin method fully initializes the CurrieBLESerial object. Call this in setup().

Syntax

cSerial.begin()

Parameters

cSerial: CurieBLESerial object

Example

/* WARNING: This is only implemented on Arduino/Genuino 101 */
#include <IoTool.h>

IoTool ioTool;

CurieBLESerial cSerial;

void setup() {
  /* Fully initialize CurieBLESerial object */
  cSerial.begin();

  /* cSerial can now be used with IoTool object */
  ioTool.setBleSerial(cSerial);
}

void loop() {
  ioTool.loop();
}