Iota Internet of Things Module – v1.20

Iota and RealTime.io Overview

ioBridge RealTime.io Cloud Server and RealTime.io Iota technology make it easy and cost effective for manufacturers to internet-enable their products. The ioBridge RealTime.io cloud server technology acts as a bridge between devices or products running RealTime.io Iota software and user applications running on smart phones, browser applications or with other third-party systems.

The Iota is available as modules or as firmware and may be integrated into products to monitor and control them over the Internet.

Main Benefits of the RealTime.io Technology

  • Ease of installation and operation. Our embedded devices are designed to be easy to install and manage. They bypass firewalls and communicate directly to an ioBridge server on the web. No port-forwarding or dynamic DNS configuration is required in most cases making installation easy for the everyday user.
  • Low cost. Rather than using Linux running on expensive CPUs, ioBridge’s embedded hardware and firmware uses low-cost microcontrollers and can leverage existing designs.
  • Easy to create new applications. ioBridge provides a web API that can be used by customers to develop their own custom applications or to integrate with their own or other third-party systems. With our off-the-shelf gateways, ioBridge provides a free web-interface and user configurable dashboard. Customers can create new a dashboard to monitor and control almost anything without writing any software.
  • Highly scalable and expandable. ioBridge’s cloud server technology is able to support 100,000 to 1,000,000 devices per server in low-traffic situations common to many internet-enabled devices.

Device or Product Side

RealTime.io Iota technology is available in three configurations:

Iota Firmware using the ioDP Core Library

The protocol used to communicate with the RealTime.io server called ioDP is available as a Library to be implemented on devices of your choice. This includes implementation on various microcontrollers with suitable Ethernet connectivity options.

Iota Modules

ioBridge currently offers an Ethernet and a WiFi module based implementations of the Iota firmware using Microchip technology. These are called the Iota Ethernet and the Iota WiFi modules. Evaluation kits for the Iota Modules with RealTime.io cloud services are available on the ioBridge Store.

Iota-based Gateway

ioBridge offers an off-the-shelf implementations of our technology. This includes ioBridge gateways such as the IO-204 and ioBridge Dashboard Applications provided free with the purchase of an off-the-shelf gateway.

Iota Evaluation Board

The Iota Eval Board exposes all of the Iota Pins, USB-to-serial conversion, provides jumpers and dip settings for common pin configurations, and status LEDs to indicate device status. Evaluation kits for the Iota Modules with RealTime.io cloud services are available on the ioBridge Store.

Iota WiFi Eval Kit

Iota Wi-Fi Evaluation Board

The Iota WiFi Evaluation Board makes it easy for developers to evaluate the functionality of ioBridge’s Iota and RealTime.io technology. This ioBridge technology makes it simple to connect new and existing products to the internet. The Iota module connects via a Wi-Fi to the ioBridge RealTime.io cloud server on the internet. Wi-Fi is simple to setup using a mobile device or by using WPS buttons on the Wi-Fi router or Hot Spot mode. » More Info

RealTime.io with Android App and Iota Module and Eval Board

RealTime.io System

The ioBridge RealTime.io system diagram is shown below and illustrates the relationship core ioBridge Technology offerings and the technology that is typically customer specific and that can optionally be developed by ioBridge.

RealTime.io Server

The RealTime.io Server is a central connection point for remote devices, web/mobile clients, backend services and system management tools. The server can be thought of as having public side that is open to internet traffic and an administrative side that is only exposed to the private enterprise network.

The public side exposes a pool UDP sockets that listen for data from devices as well as send data to devices. The public side also exposes a pool of HTTP/HTTPS API sockets that serve web clients / mobile clients and back-end services. Back-end services are applications that consume device generated data or control devices from automated software. For example a back-end service could keep a record of data sent from devices in a database or generate emails to be sent when certain conditions are met.

On the private side of the RealTime.io server is a pool a HTTP sockets for handling administrative tasks. These sockets can be bound to a separate internal IP address and protected from unwanted access. Through API calls to the administrative sockets, server statistics can be monitored and the credentials used by devices and web clients can be managed.

Another important function performed by the RealTime.io server is access authentication. Upon startup, the server pulls all relevant credential information into memory where is can be accessed instantly during device or web client communications. After start-up, an API is provided to dynamically add, change or remove privileges as needed.

ioDP (input output Data Protocol)

At the core of the communication between remote devices and the RealTime.io server is the ioDP protocol. This protocol is transparent to the end points and serves as an open, asynchronous, bidirectional data pipe. This pipe can handle plain text data as well as raw binary data. The ioDP protocol use the lightweight UDP method of transport. Although UDP is an unreliable transport on its own, reliability is added in at the ioDP layer to provide guaranteed, ordered delivery of data. To aid in situations where several different types of data are being sent simultaneously by a device, ioDP has the ability to divide data into channels that can be separated into the appropriate data streams by the server. For example, a device may need to send video as well as sensor data to the cloud. Using ioDP, the video data can be sent on a different channel from sensor data. Upon receiving the data, the RealTime.io server will route the data to the correct back-end service. The ioDP protocol provides security through AES128 encryption and a randomizing scheme to ensure that packets with identical payloads appear different after encryption is applied. For applications that require higher throughput, there is a secondary “best effort” mode in which ioDP can operate. This mode helps in applications that can tolerate a small amount of data loss such as audio and video. Finally, to keep the line of communication open for unsolicited commands to the device, an automated mechanism of keep-alive transactions is employed that is transparent to the end application. This means that the device will always be available to receive data from the cloud.

Credentialing

Every remote device is authenticated with its own ID and encryption key. Additional device credentials can be added live, while the server is running or removed if it is thought that a device has been compromised.

Web clients connect to the RealTime.io server using HTTPS or HTTP. In addition to the secure socket, the API calls performed by clients are authenticated by API keys. A single API key can give a client access to one or more devices. An API key can also assign read and write privileges separately. For example, a web application that displays sensor data may not require the ability to send commands back to the end device. In that case, an API key with read only privilege would be generated and used with the web application. API keys are managed live, through the administrative API. API keys can be added, removed or changed dynamically.

 

Iota Module Features

  • Low cost and easy to integrate SMD module designed to internet-enable a wide range of devices and products
  • Connects to ioBridge RealTime.io server technology on the Internet to easy internet-enable devices
  • Simple digital and serial interface compatible with most microcontrollers
  • Serial, analog, and digital I/O to Internet web services. I/O includes USART, GPIO
  • Pulse-Width Modulation on up to 7 pins.
  • Serial USART data communication 9600 to 115200 baud
  • Ethernet and WiFi versions
  • Enables control and monitoring behind firewalls with no port forwarding or Dynamic DNS
  • Very low latency on, typically less than 100ms
  • Scalable: one server instance can manage 100k – 1M devices depending on configuration
  • Supports message sizes up to 336 bytes
  • Acknowledgement mechanism to ensure messages reach their destination
  • Secured by 2 layers of AES-128 Encryption and CRC-16. Impervious to “man in the middle” or “replay” attacks
  • Auto recovery and reconnect in the event of a network disconnect
  • Real-time “keep-alive” optimization to reduce network load

 

Iota Pin Information

Iota Module Pinout

Iota Module Pinout

 

Pin Descriptions

Pin 1

  • Name: SPI_CS
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 2

  • Name: SPI_CLK
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 3

  • Name: DATA_READY
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 4

  • Name: ERASE_FLASH
  • Direction: Input, internally pulled high
  • Description: Holding this pin low during power up or reset will cause all the data in the Flash to be deleted. Erasing the flash data is not necessary for normal development. Avoid using this function.

Pin 5

  • Name: API_MODE_SEL
  • Direction: Input, internally pulled high
  • Description: Holding this pin low on power up or reset will cause the iota to run in API mode, otherwise the Iota will run in Raw mode.

Pin 6

  • Name: HARD_RESET
  • Direction: Input, internally pulled high
  • Description: Holding this pin low for more than 4 seconds will reset the non-volatile memory to the default configuration. For the Iota Wi-Fi, this means any stored wireless access point information will be lost.

Pin 8

  • Name: CLR_TO_SEND
  • Direction: Output
  • Description: This pin is only active when running in Raw mode with Acknowledgements enabled. It is used to indicate if the UART receive buffer is available to take in new data. This pin changes polarity depending on the state of the POLARITY pin. If POLARITY is low, CLR_TO_SEND will go low when the buffer is available. If POLARITY is high, CLR_TO_SEND will go high when the buffer is available.

Pin 9

  • Name: COM_MODE_SEL
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 10

  • Name: FLUSH
  • Direction: Input, internally pulled high
  • Description: This pin on only used when running in Raw mode. A positive going pulse on this pin will force any data in the UART receive buffer to be transmitted to the cloud immediately. Not pulsing the pin and holding the pin high, will cause the Iota to use an internal timer to automatically flush data after 20ms of UART silence. Holding the pin low will disable the internal dimer and only allow data to be transmitted to the cloud on positive going pulses.

Pin 14

  • Name: NC
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 15

  • Name: WPS
  • Direction: Input, internally pulled high
  • Description: A momentary low pulse triggers the WPS (Wi-Fi Protected Setup) access point association mechanism.  This only occurs if the Iota is not already associated with an access point. This pin is not used in Iota Ethernet version.

Pin 16

  • Name: GROUND
  • Direction: Power
  • Description: This is the Iota ground pin.

Pin 17

  • Name: 3.3V
  • Direction: Power
  • Description: This is the positive power supply connection. Only connect +3.3V.

Pin 18

  • Name: RESET
  • Direction: Input, internally pulled high
  • Description: Pulling this pin low will hold the Iota in a reset state. Returning the pin to high, will restart the Iota.

Pin 24

  • Name: DEBUG
  • Direction: Output
  • Description: This pin outputs information during start up that may be useful for debugging. The data is output using serial at a baudrate of 19200, 8 data bits, 1 stop bit and no parity.

Pin 27

  • Name: CLOUD
  • Direction: Output
  • Description: This pin goes high when a success connection have been made with the cloud. The CLOUD pin will remain high until the connection is lost.

Pin 28

  • Name: NETWORK
  • Direction: Output
  • Description: This pin goes high when an active local area network connection is detected. In the case of the Iota Ethernet, this means when a live network cable is connected. In the case the the Iota W-Fi, this means either a successful connection to an access point or the Iota is acting as an access point itself waiting to be configured.

Pin 29

  • Name: ENABLED
  • Direction: Output
  • Description: This pin goes high and stay high while the Iota is running. It is used to indicate that the firmware is running normally.

Pin 30

  • Name: SCA
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 31

  • Name: SCL
  • Direction: Not applicable
  • Description: Not used, leave disconnected

Pin 33, 34

  • Name: BAUD0, BAUD1
  • Direction: Input, internally pulled high
  • Description: These pins are used to set the initial baud rate used by the UART after start up. See Table 1 for the baud rates. If the BAUD pins are changed while the Iota is running, a reset will need to occur for the changes to take effect.

Iota Baud Rate Table

Pin 35

  • Name: POLARITY
  • Direction: Input, internally pulled high
  • Description: This pin sets the polarity of the UART_RX, UART_TX and CLR_TO_SEND on start up. Holding POLARITY high, will set the UART pins to use idle level high. Holding POLARITY low will set the UART pins to use idle level how. If the polarity is changed while the Iota is running, a reset will need to occur for the change to take effect.

Pin 36

  • Name: UART_TX
  • Direction: Output
  • Description: This is the UART transmit pin. When running in Raw mode, all data output from UART_TX will have originate from the cloud.

Pin 37

  • Name: UART_RX
  • Direction: Input
  • Description: This is the UART receive pin. When running in Raw mode, all data successfully recieved through the UART_RX pin will be sent to the cloud.

Pin 38

  • Name: ACK_MODE_SEL
  • Direction: Input, internally pulled high
  • Description: This pin is only used when running in Raw mode. If help high on start up, the messages and from the cloud will employ an acknowledgement scheme for each message. For more information about when acknowledgement should and shouldn’t be used, see sections on Acknowledgement Vs Non-Acknowledgement Mode

Pins 7, 11, 12, 13, 19, 20, 21, 22, 23, 25, 26, 32

  • Name: GPIO_X Direction: Input or Output
  • Description: This pins are for general purpose input and output. See the section on General Purpose Input Output (GPIO) Pins for more information.

 

Operational Modes

The Iota module is capable of running in either Raw or API mode. The mode is set by the voltage level on the API_MODE_SEL pin at start up or reset.

Raw Mode

Under Raw mode, the Iota acts as a “serial-to-cloud” bridge. Data sent into into the UART_RX will be forwarded on to the cloud and data received from the cloud will be transmitted out the UART_TX pin. Raw mode hides most of the complexity related to creating and managing connections with the cloud service. Raw mode is configured by setting the logic level on particular pins at start up or reset. Raw mode is designed to allow a working implementation with a minimum number of external connections; no external logic or processor is required.

API Mode

API mode is more complex but allows the use of multiple communication channels simultaneously. API mode also gives an external processor access to network and configuration settings. In order to use the Iota in API, an external process is required to initialize communications.

 

Message Reliability

Connections to the cloud service can run in Acknowledgement (ACKing) or Non-Acknowledgement (Non-ACKing) mode. These modes are separate from Raw/API modes. An Iota running in Raw mode can use acknowledgements or not by settings the ACK_MODE_SEL pin. Also, each individual cloud connection can be configured to use acknowledgements or not when using API mode.

Acknowledgement

Acknowledging is a mechanism internal to the protocol used between the Iota and the cloud. Analogous to TCP, it ensures that message reach their destination intact and in order. If messages are lost along the way, the protocol will automatically resend the messages. Likewise, not using acknowledgements is analogous to UDP.

Non-Acknowledgement

Non-ACKing mode will not resend lost packets or ensure the order across the network. However, running connections in Non-ACKing mode is much faster. Many more messages per seconds can be transmitted using Non-ACKing mode. Non-ACKing mode is appropriate for streaming media or data logging where some data loss can be tolerated.

 

Channels

The Iota uses channels to route particular kinds of data to cloud services. In this way an Iota can send multiple types of data on different channels and have the cloud act on that data efficiently. Channels are analogous to TCP ports where different protocols (HTTP, FTP, etc) run over predefined port numbers. Similarly, Realtime.io runs cloud services on predefined channel numbers and expects data to be formatted in a particular way. Channels 0 through 1023, plus channel 65535 are reserved by ioBridge to host cloud services. Channels 1024 through 65534 are free for developers to use however they want. When the Iota is running in Raw mode, a default set of channels (0, 1, 2, 3 & 65535) is used and no additional channels can used. When running in API mode, only channel 65535 is used by default. It is the responsibility of external logic that is interfacing with the Iota over API mode to create the additional channels required at run time.

Channel Name: Serial UART

  • Channel Number: 0
  • Description: Serial UART data is transmitted over this channel.

Channel Name: Data Logging

  • Channel Number: 1
  • Description: Using specially formatted messages, data sent from the Iota will be archived in a database. In Raw mode, the values of the GPIO pins are periodically sent.

Channel Name: GPIO

  • Channel Number: 2
  • Description: This channel allows access to the GPIO registers. Values from Iota’s input pins can be read and the Iota’s output pins can controlled with write commands. This is useful for situations where the developer only wants to expose GPIO functionality.

Channel Name: GPIO Triggers

  • Channel Number: 3
  • Description: This channel is used by triggered updates to push messages to the cloud when an input trigger threshold is reached.

Channel Name: Admin

  • Channel Number: 65535
  • Description: This channel allows read and write access to ALL available registers on the Iota.

 

API Key and Permissions

The ability to send data to and receive data from an Iota module via the Realtime.io Web Client API requires an API key. An API key is a alpha-numerical string obtained from the RealTime.io Api Keys tab with specific permissions associated with it. It is used in the HTTP API calls for authentication. Upon registering an Iota module in the development web interface, an default API key will automatically be generated. This key will have all permissions enabled by default. It is possible to edit this key or create a new one that has limited permissions. Permissions are configurable by channel number and operation type. Meaning a key can be made that gives the ability to transmit data from the cloud on certain channels but not others. The three configurable operation types are read, write and stream. This means that a key can be made that allows the receipt of data from the Iota but not the ability to send data in return.

 

Interfacing with the UART

The bytes of data between the Iota and the cloud are grouped into “messages”. A single message must be 336 bytes or less. The Iota automatically determines the end of a message by waiting for a 20 millisecond pause between bytes received through the UART_RX pin. Assuming bytes are received, one after another, with no break in between, the Iota will buffer the bytes until at least a 20 ms break is detected on the UART_RX pin. At which time, the Iota will forward, or “flush”, all the bytes as a single message on the cloud. If the buffer fills up to 336 bytes without a 20 ms break, the Iota will flush all those bytes as a single message. The automatic flushing after a 20 ms break can be overridden with the FLUSH pin.

The Iota is designed to work with a minimum number of connections to the developer’s circuit. Only the UART_RX, UART_TX and GROUND connections are required. However, additional connections may be used increase speed and reliability of communication. The UART operates at the baud rate set by the BAUD0 and BAUD1 pins and uses 8 data bits, 1 stop bit and no parity. The CLR_TO_SEND pin indicates when the Iota is ready to receive data.

ENABLED

Indicates that the Iota is powered and operating normally. ENABLED will go high until the there is activity regarding the NETWORK pin.

NETWORK

Indicates that an active network connection is present. In the case of the Iota Wi-Fi, this pin will also indicate when the Wi-Fi radio is available for hosting a connection.  This pin will go low once the CLOUD pin goes high.

CLOUD

Indicates that the Iota has an active connection with the cloud.

CLR_TO_SEND

Indicates that the Iota is ready to receive data over the UART_RX pin. Used only with Acknowledgement mode.

FLUSH

If held high or left disconnected, flushing will occur after 20ms of UART_RX silence or after 336 bytes have been received. If held low, periods of silence will be ignored and flushing will only occur on transitions from low to high on the pin.

 

Iota to Cloud Communication

Assuming the Iota is running in Raw mode, transmitting data into the Iota to be forwarded to the cloud is relatively straightforward. At a minimum, the UART_RX and GROUND pin must be connected to the user’s circuit. As data is received over the UART_RX pin, the Iota will buffer the bytes and watch for natural breaks in the data stream to group the bytes into messages and forward them on to the cloud.

On the cloud side, messages are routed to cloud services based on channel number and API key permissions. Messages are also delivered to HTTP streaming connection that have permission to receive the data. To create a streaming HTTP connection, first an API key must be made. See the section on API Key and Permissions for more information. HTTP streaming connections are created using the Realtime.io Web Client API. There are several methods and many options when using the streaming API. Please see the RealTime.io Web Client API for Iota Devices for more information.

 

Cloud to Iota Communication

Assuming the Iota is running in Raw mode, receiving data from the Iota that originated in the cloud is relatively straightforward. At a minimum, the UART_TX and GROUND pin must be connected to the user’s circuit. As data is received from the cloud, it will be sent out the UART_TX pin.

To send a message from the cloud, requires an API key with write permissions and use of the Realtime.io Web Client API. See the section on API Key and Permissions for more information. The following is the basic information required to send data from the cloud to an Iota for transmission out the UART_TX pin. For information regarding the sending of messages from the cloud, please refer to the RealTime.io Web Client API for Iota Devices for more information.

 

Iota Registers

Many of the internal settings of the Iota can be accessed from the cloud through registers. With that appropriate permissions, data can be read from or written to registers. Because registers have a hierarchy, multiple registers can be accesses using a single message. Registers are organized by “dot” notation with nested structures. The reading to writing of an individual register is done with a single value. The reading or writing of a register structure is done through a comma separated list of values. Register data is plain ASCII text.

Register: system.reset

  • Operations: WRITE
  • Description: Writing a 1 to this register will force the Iota module to perform a reset.

Register: system.model

  • Operations: READ
  • Description: Holds the model number of the device. The Iota Ethernet is model number 1. The Iota Wi-Fi is model number 2.

Register: system.firmware

  • Operations: READ
  • Description: Holds the firmware version running on the device.

Register: system.time

  • Operations: READ
  • Description: Holds the current Iota system time as the number of seconds since January 1, 1970 (UNIX time). Upon start up the system time will start counting from zero. Once a connection to the cloud service is established, the system clock will be updated to the current UTC/GMT time.

Register: system.wol

  • Operations: WRITE
  • Description: By writing a 12 digit MAC address to this register, the Iota will rebroadcast a Wake-On-LAN packet to the MAC address on the local area network.

Register: update.filename

  • Operations: READ / WRITE
  • Description: Writing a valid firmware file name to this register will initiate an Iota firmware update. Reading this register will return the filename that is currently being used during the update. If no update is occuring, no data will be returned.

Register: update.progress

  • Operations: READ
  • Description: Reading this register during an update will return the number of bytes of the update file that have been downloaded.

Register: update.total

  • Operations: READ
  • Description: Reading this register during an update will return the total number of byte in the update file.

Register: update.status

  • Operations: READ
  • Description: Reading this register will return the status of an update: 0 = no update started, 1 = update in progress, 2 = update successful, 128 = file transfer error

Register: network.dhcp

  • Operations: READ / WRITE
  • Description: Sets the network type. 0 = static, 1 = DHCP. The Iota must be reset for the change to take effect.

Register: network.ip

  • Operations: READ / WRITE
  • Description: Holds the local network IP address of the device. Only writable when network.dhcp = 1. The Iota must be reset for the change to take effect.

Register: network.gateway

  • Operations: READ / WRITE
  • Description: Holds the IP address of the gateway that the device is using. Only writable when network.dhcp = 1. The Iota must be reset for the change to take effect.

Register: network.dns

  • Operations: READ / WRITE
  • Description: Holds the IP address of the DNS server that the device is using. Only writable when network.dhcp = 1. The Iota must be reset for the change to take effect.

Register: network.subnet

  • Operations: READ / WRITE
  • Description: Holds the IP address of the subnet mask that the device is using. Only writable when network.dhcp = 1. The Iota must be reset for the change to take effect.

Register: network.mac

  • Operations: READ
  • Description: Holds the MAC address of the device.

Register: nvram.[address].[length]

  • Operations: READ / WRITE
  • Description: Allows access to the non-volatile RAM (NVRAM) of the Iota.  Data written to NVRAM will be remain even after resets or power cycles.  [address] is the memory address of the operation to start.  Valid addresses are 0 through 511.  [length] is the number of bytes used for the operation. Valid lengths are 1 through 128.  The “content” for the web client API call hold one or more bytes of data for the operation.  The data is formatted in ascii hexadecimal pairs with no delimiter between pairs.  For example, writing the values 8, 9, 10, 11 starting at NVRAM address 16 will use the following JSON object:
    {
    "serial":"XXXXXXXXXXXXXXXX",
    "channel":"65535",
    "register":"nvram.16.4",
    "content": "08090A0B"
    }

GPIO Registers

Register: gpio.mode.[x]

  • Operations: READ / WRITE
  • Description: Holds the mode of an individual GPIO pin, where [x] is a number from 0 to 11.

GPIO Pin Modes

Register: gpio.value.[x]

  • Operations: READ / WRITE
  • Description: Holds the value of an individual GPIO pin, where [x] is a number from 0 to 11. See Table 2 for the read/write operations and possible value ranges. In the case of digital input or digital output, the value is the logical state.  In the case of analog input, the value is the analog reading.  In the case of PWM output, the value is the pulse “on-time” in microseconds.

Register: gpio.freq.[x]

  • Operations: READ / WRITE
  • Description: Valid for only GPIO pins 2, 3, 4, 5, 9, 10 and 11.
    • When pin’s gpio mode is PWM Ouput: Holds the frequency of the pulse width modulation for the individual GPIO pin. Possible values are within the range 4 to 83333Hz.
    • When pin’s gpio mode is Digital Output: Holds a value in millisecond.  Writing to this register will trigger a positive going pulse when the value is greater than zero or a negative going pulse when the value is less than zero.  Reading this register will return the millisecond of pulse time remaining for the pulse.  Possible values are -2147483647 to +2147483647.  The smallest practical value for a pulse is 12ms.

Register: trig.interval

  • Operations: READ / WRITE
  • Description: Holds the interval, in seconds, used to automatically push GPIO data updates to the cloud. The value of this register can range from 0 to 4294967295. A value of 0 will stop pushed updates from occurring. To enable data logging by the cloud service, the log.enabled register must be set to 1. Pushed updated are only available when running in Raw mode. They are not available when running in API mode.

Register: trig.mode.[x]

  • Operations: READ / WRITE
  • Description: Holds the triggering mode for the GPIO pin, where [x] is a number from 0 to 11. Triggered updates are only available when running in Raw mode. The are not available when running in API mode.

Register: trig.lval.[x]

  • Operations: READ / WRITE
  • Description: Holds the lower triggering value for the GPIO pin, where [x] is a number from 0 to 11. For a pin set to digital, this value should be 0. For a pin set to analog, any value from 0 to 1022 can be used.

Register: trig.hval.[x]

  • Operations: READ / WRITE
  • Description: Holds the higher triggering value for the GPIO pin, where [x] is a number from 0 to 11. For a pin set to digital, this value should be 1. For a pin set to analog, any value from 1 to 1023 can be used.

Register: trig.lid.[x]

  • Operations: READ / WRITE
  • Description: Holds the lower trigger identification number for the GPIO pin, where [x] is a number from 0 to 11. The trigger identification number can be any value from 0 to 65535. When triggering is enabled on a GPIO pin and the pin hits the lower trigger threshold, the identification number will be sent to the cloud service to give notification of the event.

Register: trig.hid.[x]

  • Operations: READ / WRITE
  • Description: Holds the higher trigger identification number for the GPIO pin, where [x] is a number from 0 to 11. The trigger identification number can be any value from 0 to 65535. When triggering is enabled on a GPIO pin and the pin hits the higher trigger threshold, the identification number will be sent to the cloud service to give notification of the event.

Register: log.enable

  • Operations: READ / WRITE
  • Description: Setting this register to 1 enables periodic pushed updates of the GPIO value to the cloud service for logging. Setting this register to 0 disables the feature. This feature is only available when running in Raw mode. It is not available when running in API mode.

 

Accessing Iota and GPIO Registers

Iota registers are accessed through the Realtime.io Web Client API. The API calls require are standard HTTP(S) POST transactions with parameters set in the URL and accompanying JSON object. Please see the RealTime.io Web Client API for Iota Devices for more information.

Upper Level “Parent” Registers

In addition to reading and writing individual registers, it is possible to read to and write from multiple registers in a simple API call. This is done by accessing upper lever “parent” registers. Parent registers serialize the data stored in underlying registers and delimit the contents with commas. When reading or writing a parent register, the response will be in a predictable pattern as show below. It is possible to suppress writes to individual registers when a parent write is sent by leaving the key empty in the comma delimited array.

Register: system

Layout: 0,[system.model],[system.firmware],[system.time]

Register: gpio.mode

Layout: [gpio.mode.0], … ,[gpio.mode.11]

Register: gpio.value

Layout: [gpio.value.0], … ,[gpio.value.11]

Register: gpio.freq

Layout: [gpio.freq.2], [gpio.freq.3], [gpio.freq.4], [gpio.freq.5], [gpio.freq.9], [gpio.freq.10], [gpio.freq.11]

Register: gpio

Layout: [gpio.mode.0], … ,[gpio.mode.11],[gpio.value.0], … ,[gpio.value.11],[gpio.freq.2], … ,[gpio.freq.11]

Register: trig.mode

Layout: [trig.mode.0], … ,[trig.mode.11]

Register: trig.lval

Layout: [trig.lval.0], … ,[trig.lval.11]

Register: trig.hval

Layout: [trig.hval.0], … ,[trig.hval.11]

Register: trig.lid

Layout: [trig.lid.0], … ,[trig.lid.11]

Register: trig.hid

Layout: [trig.hid.0], … ,[trig.hid.11]

Register: trig

Layout: [trig.interval],[trig.mode.0], … ,[trig.mode.11],[trig.lval.0], … ,[trig.lval.11],[trig.hval.0], … ,[trig.hval.11],[trig.lid.0], … ,[trig.lid.11],[trig.hid.0], … ,[trig.hid.11]

Register: network

Layout: [network.dhcp],[network.ip],[network.gateway],[network.dns],[network.subnet],[network.mac]

Register: update

Layout: [update.filename],[update.progress],[update.total],[update.status]

General Purpose Input / Output (GPIO) Pins

The Iota has 12 pin available for user input/output. All the GPIO pins are individually configurable. All GPIO pins have digital capability, while only GPIO_1 through GPIO_8 have analog input capability. The pin with analog input capability are tolerant to +3.3V. The remaining GPIO pins are tolerant to +5.5V. PWM output is available on 7 GPIO pins.  The GPIO settings and readings are controlled through internal registers. The registers are only accessible through cloud service by using the Realtime.io Web Client API. The Iota must be powered on and connected to the cloud in order to access the GPIO registers.

The data written to gpio, trig and log.enable registers are stored in non-volatile memory. Upon start up, the Iota will configure the GPIO pin modes and set digital outputs to their last known states. During the brief time between applying power and setting the pins to the proper states, the pins are defaulted to inputs. External weak pull-up or pull-down resistors are recommended in situations where a brief period of logic uncertainly cannot be tolerated.

The GPIO pins can be set to the following modes:

0 – digital output, pulse output, 0/3.3V
1 – digital output, pulse output, open drain
2 – digital input, pulled-up
3 – digital input, pulled-down
4 – analog input
5 – pwm output
6 – pwm output, open drain

GPIO Pin Capabilities

Triggered Updates

Sometimes it is useful to send a message from the Iota to the cloud when a digital input pin changes state or when an analog input reaches a predefined threshold. This can be accomplished through the use of the triggered update, “trig”, registers. Each GPIO pin be individually configured for triggering. The actual trigger message sent to the cloud includes the GPIO pin number, pin value and trigger identification number. The trigger identification number is used by the cloud service to determine what action to take.

Using a triggered update involves setting a few registers.

  1. Set the gpio.mode.x of the pin
  2. Set the trig.lval.x and trig.hval.x to the lower and higher trigger thresholds. For a digital input, the lower and higher thresholds will be 0 and 1, respectively.
  3. Set the trig.lid.x and trig.hid.x. If a cloud service will not be taking action on the trigger update messages, it is not necessary to set these registers.
  4. Set the trig.mode.x according to the Trigger Mode table below.

Trigger Modes:
0 – never send update
1 – send update on low or high value
2 – send update on low value only
3 – send update on high value only

Once the trigger mode is set to a non-zero value, messages will be automatically sent to the cloud when a trigger occurs. If the value read by the Iota hits a trigger threshold while offline, the message will be sent when the Iota reconnects to the cloud.

Periodic GPIO Updates

The Iota has the ability to automatically send GPIO readings to the cloud at a defined interval. This is done be setting the trig.interval register to a non-zero number that corresponds to the number of seconds between GPIO updates. When the Iota sends the periodic update, the message sent is actually the contents of the gpio parent register. These periodic updates can be seen in the Web Client API stream on the channel 3 (GPIO Read Only). To use cloud data logging in combination with periodic GPIO updates, set the log.enable register to 1. This will cause the Iota to send the GPIO values to the cloud data logging service for archiving and later retrieval.

Pulse Width Modulation (PWM)

Some GPIO pins have PWM output capabilities.  Each GPIO pin set to use PWM can be configured with an independent frequency and duty.  The frequency is set through the gpio.freq.[x] registers or an upper level gpio register.  The frequenecy is set in Hertz within the range 4 to 83333.  Not all frequencies within that range can be used.  Upon setting the frequency, the Iota will reply with the closest frequency that was achieved.  The PWM duty is set through the gpio.value[x] register or upper level gpio register.  The value is the pulse “on-time” in microseconds.  Not all values within the range of 8 to 250,000 microseconds are possible.  Upon settings the value, the Iota will reply with the closest duty that was achieved.  Setting the on-time value to a duration longer than the PWM period (1/frequency) will result in a GPIO that is consistently high. Setting the duty value to a value of 0 will result in a GPIO that is consistently low.

Pulse Output

Some GPIO pins have the ability to pulse when set as a digital output.  Writing a value, in milliseconds, to the gpio.freq.[x] register or upper level register will trigger the pulse.  Reading the register during the pulse will return the time remaining in milliseconds.  After the pulse is finished, the register will be set to zero automatically.  A positive value will trigger a positive going pulse and a negative value will trigger a negative going pulse.  The smallest pulse possible is 12ms.  The largest pulse possible is 2147483647ms.  It should be noted that pulses to not remain active after a power cycle.  After a power cycle, the pin will revert to the state prior to the pulse being triggered.

Non-Volatile RAM (NVRAM)

The Iota allows access to a block of 512 bytes of non-volatile RAM.  Data written to NVRAM will survive resets and power cycles.  The NVRAM is very high endurance and can be written to millions of times.  Reads and writes to NVRAM can be performed via the web client API through the nvram registers.  Also, reads and writes to the NVRAM can be performed via hardware-level keys when using API mode.  See the sections on Iota Registers and Hardware-level Keys for more information.

Using API Mode

Holding the API_MODE_SEL pin low on start up or reset will cause the Iota to run in API mode. API mode allows greater flexibility in creating multiple independent channels and adjusting system settings. To use API mode, an external processor must interact with the Iota over the UART pins. The standard UART pass-through functionality is not available in Raw mode. Upon start up in API mode, the Iota will make a single connection on the Admin channel. However all other channels will need to be created and managed manually through the API command. API commands are sent in raw binary and responses from the Iota are returned in raw binary.

There are two main types of operations: read and write.

There are several parts to an API operations and response. The following is those parts and some short descriptions.

  • [start byte] – a single byte with the value 0x7E
  • [message length] – a two byte unsigned integer representing the number of byte in the remainder of the message, least significant byte first.
  • [read] – a single byte, value of 0x01, that indicated a read operation
  • [write] – a single byte, value of 0x02, that indicated a write operation
  • [ack] – a single byte, value of 0x03, that indicated a successful operation
  • [nack] – a single byte, value of 0x04, that indicated an failed operation
  • [key address] – a two byte unsigned integer representing the key address, least significant byte first.
  • [data] – one or more byte of data
  • [checksum] – a two byte checksum

Checksum

The checksum used by Iota API is Fletcher-16. This style of checksum is sensitive to byte value, byte order, missing nulls and still relatively light simple.

Pseudocode for creating a Fletcher-16 checksum:

integer i, sum1, sum2;
BYTE check1, check2,
sum1 = 0;
sum2 = 0;

for i = 1 to message_length
sum1 = (sum1 + message[i]) mod 255;
sum2 = (sum2 + sum1) mod 255;
next

check1 = 255 - ((sum1 + sum2) mod 255);
check2 = 255 - ((sum1 + check2) mod 255);

message[message_length + 1] = check1;
message[message_length + 2] = check2;

check1 and check2 are the byte to be appended to the end of an API call

Pseudocode for confirming a Fletcher-16 checksum:

integer i, sum1, sum2;
BYTE check1, check2,
sum1 = 0;
sum2 = 0;

for i = 1 to message_length
    sum1 = (sum1 + message[i]) mod 255;
    sum2 = (sum2 + sum1) mod 255;
next

if sum1 = 0 AND sum2 = 0 then
    passes
else
    error detected
end if

Write Operation Format:

[start byte][message length][write][key address][data][checksum]

Write Operation Successful Response Format:

[start byte][message length][ack][checksum]

Write Operation Unsuccessful Response Format:

[start byte][message length][nack][checksum]

Read Operation Format:

[start byte][message length][read][key address][checksum]

Read Operation Successful Response Format:

[start byte][message length][ack][data][checksum]

Read Operation Unsuccessful Response Format:

[start byte][message length][nack][checksum]

 

Hardware-level Keys

Address: 0x0010

  • Name: ERROR_CODE
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Not used

Address: 0x0011

  • Name: STATUS_MAC
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: 0 = no network connection, 1 = network connection

Address: 0x0012

  • Name: STATUS_DHCP
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: 0 = DHCP not bound, 1 = DHCP is bound

Address: 0x0013

  • Name: STATUS_DNS
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: 0 = domain name not resolved, 1 = domain name resolved

Address: 0x0014

  • Name: DHCP_ENABLE
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: 0 = static, 1 = DHCP. The iota module must be reset for change to take effect.

Address: 0x0015

  • Name: LOCAL_HOST
  • Operations: Read/Write
  • Byte Length: 4
  • Data Type: unsigned byte array, most significant byte first
  • Description: The Iota’s local IP address. Only writable when DHCP_ENABLE = 0. Change takes effect after reboot.

Address: 0x0016

  • Name: GATEWAY
  • Operations: Read
  • Byte Length: 4
  • Data Type: unsigned byte array, most significant byte first
  • Description: The Iota’s gateway address. Only writable when DHCP_ENABLE = 0. Change takes effect after reboot.

Address: 0x0017

  • Name: DNS
  • Operations: Read
  • Byte Length: 4
  • Data Type: unsigned byte array, most significant byte first
  • Description: The Iota’s DNS address. Only writable when DHCP_ENABLE = 0. Change takes effect after reboot.

Address: 0x0018

  • Name: SUBNET_MASK
  • Operations: Read
  • Byte Length: 4
  • Data Type: unsigned byte array, most significant byte first
  • Description: The Iota’s subnet mask. Only writable when DHCP_ENABLE = 0. Change takes effect after reboot.

Address: 0x0019

  • Name: MAC
  • Operations: Read
  • Byte Length: 6
  • Data Type: unsigned byte array
  • Description: The Iota’s MAC address.

Address: 0x001A

  • Name: BAUDRATE
  • Operations: Read/Write
  • Byte Length: 4
  • Data Type: unsigned longword, least significant byte first
  • Description: The baud rate of the UART, unsigned long , least significant byte first. The new baud rate will take effect after the ack response.

Address: 0x001B

  • Name: RESET
  • Operations: Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Writing a 1 will force the Iota to perform a system reset.

Address: 0x001C

  • Name: WIFI_MODE
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: 1 = Infrastructure, 2 = Adhoc, 4 = SoftAP

Address: 0x001D

  • Name: WIFI_SSID
  • Operations: Read/Write
  • Byte Length: 32
  • Data Type: character array
  • Description: The SSID of the target Wi-Fi Access Point.

Address: 0x001E

  • Name: WIFI_KEY
  • Operations: Read/Write
  • Byte Length: 64
  • Data Type: character array
  • Description: The key/password of the target Wi-Fi Access Point

Address: 0x001F

  • Name: WIFI_SECURITY
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: The security type of the target Wi-Fi Access Point.

Address: 0x0020

  • Name: WIFI_REGION
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: The regional domain of the target Wi-Fi Access Point. 0 = FCC, 2 = ETSI, 7 = Japan

Address: 0x0021

  • Name: ACK_TIMEOUT
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: The number of seconds to wait for an acknowledgement before a message is considered lost.

Address: 0x0022

  • Name: MAX_RETRIES
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type:
  • Description: The maximum number of failed message retries before the cloud is considered disconnected

Address: 0x0023

  • Name: KPALV_AUTO
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: 0 = disable keep-alive optimization algorithm, 1 = enable keep-alive optimization algorithm

Address: 0x0024

  • Name: KPALV_MANUAL_VAL
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: The number of seconds between keep-alive messages if keep optimization is disabled

Address: 0x0025

  • Name: TIME_UNIX
  • Operations: Read
  • Byte Length: 4
  • Data Type: unsigned longword, least significant byte first
  • Description: The number of seconds since Jan 1, 1970, GMT.

Address: 0x0026

  • Name: TIME_GMT
  • Operations: Read
  • Byte Length: 19
  • Data Type: character array
  • Description: The GMT time in the format YYYY-MM-DD_HH:NN:SS

Address: 0x0027

  • Name: SOCKET_TARGET
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Set this to the desired socket handle before reading other socket keys, reading the BUFFER_RX or deleting a socket.

Address: 0x0028

  • Name: SOCKET_CREATE
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Writing a 1 to this key will initiate

Address: 0x0029

  • Name: SOCKET_CHANNEL
  • Operations: Read/Write
  • Byte Length: 2
  • Data Type: unsigned word, least significant byte first
  • Description: The channel number of a socket. To read the channel number, the SOCKET_TARGET key must be set first.

Address: 0x002A

  • Name: SOCKET_SIZE
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: That message buffer size in bytes of a socket. To read the socket size, the SOCKET_TARGET key must be set first. The buffer size must be a multiple of 12.

Address: 0x002B

  • Name: SOCKET_MODE
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: The acknowledgement mode of a socket, 0 = Non-ACKing, 1 = ACKing. To read the socket mode, the SOCKET_TARGET key must be set first.

Address: 0x002C

  • Name: SOCKET_RESULT
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Upon creating a new socket with SOCKET_CREATE, read this key to get to the newly created socket’s handle.

Address: 0x002D

  • Name: SOCKET_DELETE
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Deletes a socket. The socket handle must first be written to SOCKET_TARGET.

Address: 0x002E

  • Name: SOCKET_STATUS
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Returns the sockets connection status. 0 = socket doesn’t exist, 1 = socket created, 2 = socket enabled, 3 = UDP port open, 4 = socket is attempting connection, 5 = socket connected to cloud

Address: 0x002F

  • Name: BUFFER_TX
  • Operations: Write
  • Byte Length: up to 336
  • Data Type: unsigned byte array
  • Description: Data written to this key will get sent to the socket selected by SOCKET_TARGET.

Address: 0x0030

  • Name: BUFFER_RX
  • Operations: Read
  • Byte Length: up to 336
  • Data Type: unsigned byte array
  • Description: An unread message from the cloud will be held in this key. An acknowledgement will not be returned to the cloud until the buffer is read. If no message is available, the buffer will be empty.

Address: 0x0031

  • Name: RAM_TOTAL
  • Operations: Read
  • Byte Length: 2
  • Data Type: unsigned word, least significant byte first
  • Description: The total RAM in bytes of Iota memory for sockets.

Address: 0x0032

  • Name: RAM_AVAILABLE
  • Operations: Read
  • Byte Length: 2
  • Data Type: unsigned word, least significant byte first
  • Description: The unused RAM in bytes.

Address: 0x0033

  • Name: SERIAL_ID
  • Operations: Read
  • Byte Length: 16
  • Data Type: unsigned byte array
  • Description: The 16 byte serial ID unique to every Iota.

Address: 0x0034

  • Name: FIRMWARE_VERSION
  • Operations: Read
  • Byte Length: 2
  • Data Type: unsigned byte array
  • Description: The firmware version of the Iota. The first byte is the minor revision. The second byte is the major revision.

Address: 0x0035

  • Name: MODEL_ID
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: The model number of the Iota. 1 = Iota Ethernet, 2 = Iota Wi-Fi

Address: 0x0036

  • Name: SOCKET_CLR_TO_SEND
  • Operations: Read
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Returns 1 if a socket is ready to receive messages data through the BUFFER_TX key. To read, the SOCKET_TARGET key first.

Address: 0x0037

  • Name: NVRAM_LENGTH
  • Operations: Read/Write
  • Byte Length: 1
  • Data Type: unsigned byte
  • Description: Sets the number of bytes to be returned when an NVRAM address key is read.

Address: 0x0100 to 0x02FF

  • Name: NVRAM_ADDRESS
  • Operations: Read/Write
  • Byte Length: For a read operation the byte length is set by NVRAM_LENGTH.  For a write operation, the byte length is variable up to 256.
  • Data Type: unsigned byte array
  • Description: Key address 0x0100 corresponds to NVRAM address zero, Key address 0x0101 corresponds to NVRAM address 1 and so on.

Process to Create Sockets

  1. Power up Iota and wait 500 ms for initialization period to complete
  2. Write the desired channel number for the new socket to SOCKET_CHANNEL.
  3. Wait for ACK
  4. Write the desired buffer size for the new socket to SOCKET_SIZE.
  5. Wait for ACK
  6. Write the desired mode for the new socket to SOCKET_MODE.
  7. Wait for ACK
  8. Write a 1 one SOCKET_CREATE
  9. Wait for ACK
  10. Read SOCKET_RESULT to get the newly created socket’s handle
  11. Return to step 4 to create additional sockets

Process to Send Message Data to the Cloud

These steps assume a socket has been created as in ‘Process to Create Sockets’

  1. Write the socket handle to SOCKET_TARGET
  2. Wait for ACK
  3. Read SOCKET_CLR_TO_SEND
  4. If SOCKET_CLR_TO_SEND = 0, return to step 2
  5. Write message data to BUFFER_TX
  6. Wait for ACK

Process to Receive Message Data from the Cloud

These steps assume a socket has been created as in ‘Process to Create Sockets’

  1. Write the socket handle to SOCKET_TARGET
  2. Wait for ACK
  3. Read BUFFER_RX
  4. Wait for ACK with message data
  5. If an empty message is returned, there is no message

Process to Delete Sockets

These steps assume a socket has been created as in ‘Process to Create Sockets’

  1. Write the socket handle to SOCKET_TARGET
  2. Wait for ACK
  3. Write a 1 to SOCKET_DELETE
  4. Wait for ACK

API Mode RAM Usage

When running in API mode, it is possible to create several sockets that run simultaneously. The maximum number of sockets that can be create is 15. However, each additional socket requires an area of RAM to hold socket states and buffer message data. The amount of RAM is available at run-time, through the RAM_AVAILABLE key. The amount of RAM required for a socket can be calculated with the following equation.

RAM for one Socket, ACKing mode = 2 x S + 256

RAM for one Socket, Non-ACKing mode = S + 202

where S is the message buffer size

 

Iota Schematic

Iota Schematic

Iota Dimensions

Iota Ethernet Physical Dimensions

 

Iota WiFi Physical Dimensions

Recommended Footprints

Iota Ethernet Recommended Footprint (Recommended 2mm copper keep-out from hole edges.)

 

Iota WiFi Recommended Footprint

 

RealTime.io and Iota Support

Firmware Change Log

v1.18 – Documentation

  • Added support for Iota Wi-Fi
  • Added registers and keys for reading on board non-volatile RAM
  • Added support for pulse-width modulation
  • Changes structure of GPIO register to hold PWM frequencies
  • WPS feature for Wi-Fi is now on pin 15

v1.20

  • Added support for Pulse Output
  • Modified ENABLED, NETWORK and CLOUD signals to only allow one to be high at a time