IOT Developer Guide

Technical documentation

Version 1.4

thingsonedge.com

Copyright © 2020 Things On Edge Limited.

All rights reserved.

Cambridge, UK

TABLE OF CONTENTS:

About data privacy

About this guide

Platform

Cricket Wi-Fi module

Overview

Applications

Functional description

Cloud service

TOE Developer Portal service

TOE MQTT service

Integration to 3rd party services

Hardware

Specification

Pinouts

Power supply

Compatible batteries

Recommended operating conditions

Temperature sensor

Reducing power consumption for a single event

Reducing the number of events

RTC

IO ports

Configuration

Device registration

Forget / Remove device

Device configuration

Retrieving configuration on your device

Connectivity

Pair device to Wi-Fi network

Pair from Mobile app

Communication channels

MQTT

MQTT client configuration

MQTT subscribe topics for clients

HTTP POST Requests

Examples

HTTP POST request example: A button for sending emails over IFTTT

HTTP POST request with payload tags example

MQTT Example: use Mobile app

Complete examples

IoT Moisture Sensor - based on MQTT

IoT Button with IFTTT integration

IoT Motion Sensor with Email alerts

Home Assistant integration

About data privacy

Things On Edge keeps it very simple. We DO NOT collect nor track any user data from anyone! We love developing technology which serves people. We live from selling this technology i.e. Cricket modules.

We use personal data for two purposes only:

  1. Purchases and shipments of products from Things On Edge - Store
  2. Developer Portal account (email and encrypted password only) to manage Cricket modules

Things On Edge Mobile app doesn’t require any user’s account or data it works without any login, which is another proof that we are not interested in your personal data.

About this guide

This guide provides a technical background of what developers can do with IOT Cricket Wi-Fi module, what components (buttons, sensors, etc.) you can attach to it, how Cricket works, how it connects to the internet, what services you can use, what communication channels are available such as MQTT and HTTP POST requests and many more.

The Platform section provides a high level overview of a complete platform which comes with a Cricket module.

The Hardware section contains technical information about the module such as power supply requirements, type of compatible batteries and many more. It is to give you an idea of what components you can attach to it.

The Configuration section provides technical information on how you configure devices entirely over-the-air from the Developer Portal cloud service. It also provides more information on how devices retrieve configurations from there.

The Connectivity section provides information on how you connect your devices to a Wi-Fi network.

The Communication channels section provides essential information on how you integrate your devices with the IOT ecosystem of apps and services available in the internet. As it is not possible to explain all available services we picked up a few examples to give you an idea of how you can use your favourite services. It also explains what you need and how you configure it to receive notifications/data either on your phone, computer or any other services.

Platform

Things On Edge provides a complete IOT connectivity platform for you. It includes the following components:

  1. A physical IOT Cricket Wi-Fi module - needs to be physically integrated into your device
  2. FREE Cloud service - comes pre-integrated with Cricket
  3. Integration to 3rd party internet services and application ecosystems

The platform allows you to connect your device to the internet by simply incorporating a Cricket module into your device. It makes the device automatically connected to a huge ecosystem of internet services and mobile apps (IOT). You also choose communication channels that you want the data and events to be sent to the internet (smartphone, laptop, PC or other services). Despite Cricket connects over standard Wi-Fi it can be directly powered from a battery (AAA, AA, …) - for years when utilising a true 0A feature.

See the diagram below which shows how robust connectivity options you have while using the Cricket module.

Cricket Wi-Fi module

Overview

Cricket is an ultra-low battery powered IoT Wi-Fi module. It doesn't require IOT hubs, any coding or programming to connect your devices to the internet. It comes with a pre-installed software and integrated FREE Cloud service (Developer Portal & MQTT service). You can configure Cricket's connectivity out of the box either from a smartphone or a laptop from any web browser. This means you do it entirely over the air. Manage device(s) remotely and integrate them to other systems using either MQTT protocol or HTTP POST Requests (Webhooks, IFTTT, …). All this is explained in more details later in this guide.

Cricket can be powered directly on batteries so you do not have to worry about wiring cables. It can simply be put remotely at home or in the garden, without wires, up to 100 meters away from a Wi-Fi router.

It comes with set of great features which you can utilise in your device:

  1. Ultra-low power, true 0A current when not in operation
  2. Operates directly on batteries below 3.5V (AA, AAA, AAAA, ...)
  3. Built-in configurable Real-Time Clock (RTC) for regular wake ups with specified time intervals
  4. Built-in configurable temperature sensor
  5. Configurable battery monitor
  6. Configurable Analog or Digital input for sensors
  7. Remote configuration (from the Developer Portal)
  8. Configurable MQTT (use either FREE Things On Edge or any 3rdparty MQTT broker)
  9. Configurable HTTP POST Requests

Applications

Cricket has been designed to report events/actions and data immediately from remote environments (e.g. home, garden, ...) directly to client devices with a very low latency (~3 seconds). Although it can be used for ad-hoc controlling remote devices it is not recommended due to the latency - it might be too long (more than 10 seconds). Think about Cricket as a connectivity module to send instantaneously data & events from various sensors, buttons and the like for example: a button was pressed; a temperature dropped, etc.

You may already have an idea where you could use Cricket. It is a great module if you plan to build devices reporting events and data from remote environments i.e. home, garden etc..

For example:

 > Report notifications when someone is at your doorstep

 > Ring your phone when someone rings a doorbell

 > Report moisture level in a flower

 > Set alarm on your phone when the moisture level goes below or above certain thresholds

 > Report a local temperature information (garden / home / room)

 > Report information about windows / doors are closed / open

 > Report information when alarm goes off

 > Report a detected movement either via email or ringing your phone

 > Report noise detection

 > … there are literally endless applications for reporting data and information from any sensory devices that you can use Cricket for.

Functional description

The Cricket module have 2 operation modes: Normal & Binding

Normal

Normal mode is triggered either by an internal RTC or a signal raised on the WAKE_UP pin by a connected external component.

Power-up & Initialization. When the module wakes up it performs the following firmware initialisations:

 > Load FW from non-volatile memory

 > Read configuration from non-volatile memory (fetched from Developer Portal)

 > Initialize platform modules such as RTC, temperature sensor and GPIO’s.

Once the board is initialized it performs sensors evaluation. Only sensors which were configured in Developer Portal are evaluated for example if the temperature sensor is not enabled the module will not read current temperature from the sensor.

Evaluation. There are a number of steps applied for each sensor evaluation process such as:

 > Read the current value

 > Store the current value in non-volatile memory

 > Only if the current and stored values are different or “Force updates” is on then the current value is sent to the internet. It is sent via either HTTP POST request or MQTT protocol which you configure form within Developer Portal.

Wi-Fi Enable. The Wi-Fi connectivity process is conditionally triggered based on the evaluation process.

IF at least one value needs to be sent to the internet

OR “Force Updates” is enabled

THEN the WiFi is enabled

ELSE the board will power off and wait for another trigger

Cricket connects to Wi-Fi which is set during the Pairing / Binding process described further in this guide.

Cloud update. Once the WiFi connection is established, the module sends data & events to the internet. There are currently two methods available:

 > Send data directly via MQTT broker (configure any MQTT broker e.g. Hive, CloudMQTT, …)

 > Send data directly via HTTP server (either a custom user server or existing service e.g. IFTTT) using POST request

After Cricket sends data, it powers off and waits for another trigger. Both these methods are described further in this document.

Binding

The binding (also known as pairing) process is activated when you press an on-board button for 5 seconds.

         

You know when the Binding process is active with the LED status. The LED should be constantly lit (not blinking). The board opens up toe_device Wi-Fi hotspot for 2 minutes. Then you can connect either from a laptop or a smartphone to this hotspot and pair Cricket to your Wi-Fi network. It is explained in more detail in the “Wi-Fi pairing” section.

After 2 minutes the board powers off. If you do not manage to pair your network on time you can repeat the process by pressing the button for 5 seconds once again.

Cloud service

Things On Edge provides a very efficient and low latency Cloud which comes pre-integrated with the Cricket module. The Cloud is FREE of charge for Cricket’s users and it provides the following services:

 > TOE Developer Portal service - configure / program your devices remotely

 > TOE MQTT service - low power and low latency direct communication with client devices

The diagram above shows a high level overview of how Cricket and other devices can be connected. You can also use other communication channels / services with 3rd party MQTT brokers and HTTP POST requests that do not require Things On Edge cloud. Cricket connects and sends data directly to those services. All these are explained in more detail further down in this guide.

TOE Developer Portal service

The Developer Portal service is an integral part of the Cricket module. The module comes with this pre-integrated service and cannot be configured otherwise. It lets you tailor a Cricket behaviour for your device. As it is shown below on the diagram every time Cricket connects to the internet it retrieves the latest configuration from the portal.

In other words TOE Developer Portal makes it extremely easy for you to configure and program Cricket modules over the air. It is done remotely from any device connected to the internet (Smartphone, Laptop, PC, …) and what is best of all it can be done without writing a single line of code and using any programmers.

See the Configuration section for more details on how you can configure your device.

TOE MQTT service

“MQTT is an open OASIS and ISO standard (ISO/IEC PRF 20922) lightweight, publish-subscribe network protocol that transports messages between devices” (source Wikipedia)

Things On Edge provides a highly efficient and low latency MQTT broker. The Cricket module has a built-in native MQTT support and comes with this pre-integrated MQTT service. This service provides a direct, reliable and low latency connectivity which results in ultra-low power consumption of the Cricket module. You can also configure any other 3rd party MQTT broker to which Cricket directly sends data and events.

This service allows you and users to receive data and events directly on their devices (Smartphone, Laptops, …) by using off the shelf wide range of mobile apps and internet services.

Integration to 3rd party services

The Cricket module comes with a flexible integration to 3rd party internet services by using either MQTT or HTTP POST requests (Webhooks). Cricket sends events and data directly to these services. It does not require Things On Edge cloud. You configure it from within the Developer Portal.

It opens up for you endless Cricket configuration options with the internet services such as IFTTT for example (but it can be anything else even your custom local server)..

Hardware

Specification

Physical dimensions

Length: 37.6 mm

Width: 16.2 mm

Height: 3 mm

Operating wireless range

Up to 100 meters

Wi-Fi

2.4GHz

802.11 b/g/n WPA / WPA2

Operating Voltage

1V~3.7V

Operating Temperature Range:

-20°C~80°C

Chipset

ESP8266EX

CPU 32bits @160MHz

Pinouts

Pin

Description

GND

Ground

IO3

Reserved

IO2

Digital or Analog input signal

WAKE_UP

HI level on that pin will turn board on

3V3

Output power from internal regulator. This is always 3.3V regardless on BATT voltage level

BATT

Power supply VDD to the board, this can be connected directly to a battery (see compatible batteries section)

Power supply

Power supply is designed to operate directly on the batteries and provide low power consumption for both when operating and not operating in power-off state.

In order to power-up the module the power source must provide at least 100mA@3.3V continuously and 0.5A@3.3V for ~1ms peak which usually occurs once per wake up.

Compatible batteries

Cricket’s operating voltage is 1V - 3.5V and can be powered almost on any battery. However you need to pay attention to the battery voltage as you might need to use a DC-DC step down regulator. All batteries below 3.5V can power Cricket directly and all higher than 3.5V must use the step-down regulator.

Recommended operating conditions

The table summarises general operating conditions for the Cricket module which needs to be met.

Operating Condition

Symbol

Min

Max

Typical

Unit

Supply voltage

BATT

1

3.6

3

V

Wake up voltage

WAKE_UP

1

3.6

3

V

Operating temperature

-20

80

20

Temperature sensor

Cricket has a built-in temperature sensor TMP1075DSG. It has the following parameters shown in the table below.

Operating Condition

Value

Unit

Temperature range

−40°C to +75°C

°C

Resolution

0.5

°C

Accuracy

±1

°C

The temperature is evaluated only if the sensor is enabled. You can configure the sensor in Developer Portal. It is important to note that the temperature value, such other sensors, are not always sent to the cloud. The table below illustrates scenarios when the temperature value is sent to the cloud on every wake up event.

Temp value
(initial value 20)

Cloud update

Force updates: OFF

Force updates: ON

20.0

NO

YES

20.5

YES *

YES

20.5

NO **

YES

20.0

YES  *

YES

* temperature value is sent to the cloud because is different compared to previously cached value by at least 0.5°C

** temperature is not sent because the difference is less than 0.5°C

When “Force Updates” is on then Cricket sends the temperature value to the cloud on every wake up event, regardless of values cached previously.

You can extend the battery life of your device by tweaking a few parameters. For the temperature measurements you can think of the two key aspects to reduce the power:

 > Reducing power consumption for a single event

 > Reducing the number of events

Reducing power consumption for a single event

One of the Cricket’s features is that it caches evaluated values from sensors by default. They are compared to the currently evaluated values from sensors and only if the values are different they are sent to the internet. Below there are two wake ups shown with sending and not sending data.

The first wake_up event does only FW initialization and sensor evaluation. Cricket determines that cached and current values are the same and there is no need to send data to the cloud.

The second wake_up event does FW initialization, sensor evaluation and sending data to the cloud. Cricket determines that cached and current values are different and sends data to the cloud.

On average you can reduce 6x power consumption of the batteries when Cricket doesn’t have to send data to the internet after sensor evaluation. You can save even more power when the Wi-Fi router and the internet connectivity happens to be slow.

It is recommended to keep “Force Updates” disabled to reduce connectivity to minimum and extend the battery life.

Reducing the number of events

Reducing the number of events with averaging temperature is another aspect of reducing power consumption. By decreasing the temperature sensor resolution, which also reduces the ambient temperature noise, you can reduce the number of connections respectively. Cricket performs less internet connections which results in more power saving. An example below shows the difference between the temperature read from the sensor and the average temperature of 8 samples.

The blue line in the graph represents a real temperature measurement in a home environment. It shows thermal noise usually not bigger than 0.5°C. However this may produce a significant number of unnecessary events for Cricket to send data to the internet and unnecessary power consumption. This can be reduced with the averaging temperature function which Cricket already has for the built-in temperature sensor. The red line shows a calculated average by Cricket from 8 recent samples. The graph shows an effective way of reducing either noise or spikes. It not only results in producing accurate results but also significantly improves the battery life.

 

The averaging function takes N recent values stored in cache and calculates the average value, which then is stored in cache.

You can configure it from Developer Portal. The averaging samples option appears only when the temperature sensor is enabled.

Both the “Temperature Moving Average” parameter and wake up frequency can be tuned to increase battery life time. The wake up frequency can be further tuned with the RTC, which is explained below.

RTC

Cricket has a built-in RTC (Real-Time-Clock) module for regular wake ups. You can configure it with a selected time interval from Developer Portal with the following units: Seconds, Minutes or Hours. They cannot be mixed. For example you can set a 3 hour time interval but not 3 hour and 30 min. Below you can find more details on power requirements and how it works.

The RTC requires ~0.3uA. It is connected directly on the battery power domain. Thus it remains powered on even when Cricket is off as long as the battery provides continuous voltage.

When RTC reaches the end of the configured period of time, it wakes up Cricket by providing a power supply to MCU. Then MCU boots FW which makes Cricket to enter into “Normal” mode operation described in the Functional description section. When RTC interrupt occurs FW reloads the alarm interval from the current configuration.

The RTC works with other wake up external sources connected to the WAKE_UP port.

T1, T2, T3, … RTC time interval set 30 min from Developer Portal

The diagram above shows mixed WAKE_UP signals. The first and second (green) wake ups come from the pre-configured RTC with a specified time interval (30 min). The next signal (blue) comes from the WAKE_UP pin and occurs in the middle of the RTC interval time. This (blue) signal wakes up Cricket, resets RTC to the pre-configured time (30 min) and restarts counting from 0 min. The last wake up (green) comes from RTC 30 min after the blue wake up.

By default Cricket does not send data to the internet on every RTC wake up. Unless values have changed. If you want Cricket to send data regardless of values being changed, set “Force Updates” -> “RTC Wake Up” to “Yes” from Developer Portal.

IO ports

Cricket has a general purpose IO port marked as IO2 / ADC on the board. You can configure this port as either Analog or Digital input from Developer Portal.

Digital input port characteristics

Operating Condition

Min

Max

Typical

Unit

VIL

0

0.7

0

V

VIH

1

3.5

3.3

V

Analog input port characteristics

Operating Condition

Min

Max

Unit

Resolution

1

8

bits

Voltage range

0

3.5

V

Cricket sets the analog input resolution to 8 bits by default. However if you do not require such high resolution as you might want to reduce noise; reduce the number of events sent to the internet; or any other reasons you can change it. Go to Developer Portal and set the “IO2 Analog Divider” parameter with a desired value, which represents a number of bits. Note the  parameter appears only when you select “Analog In” for IO2.

Analog value is an integer, which is sent to the cloud. It can be converted back to the input voltage with following formula:

Vin = (Vref / 28 - “IO2 Analog Divider”) * IO2

Where

IO2:

Value reported by Cricket to the cloud (see MQTT and HTTP POST Requests). The value range depends on the “IO2 Analog Divider” parameter (see the table below).

Vref:

3.5

“IO2 Analog Divider”:

Number of bits (max. 7) configured from Developer Portal (see Device configuration)

IO2 Analog Divider

Max IO2 value

0

256

1

128

2

64

3

32

4

16

5

8

6

4

7

2

Configuration

Configuring a.k.a. programming of the Cricket module is done entirely OTA (Over The Air) from TOE Developer Portal (https://dev.thingsonedge.com) without coding and programming.

The Developer Portal offers the following functionality:

 > Developer account Login / Registration

 > Device registration / assignment

 > Device configuration

 > Remove / Forget devices from your account

The portal is designed for you to produce devices for end users. You define connectivity behaviour of your devices there in the portal. You are the only one who has access to change configuration of devices you build. Your users do not, they cannot change device functionality. However there may be more than one user receiving data and events, specified by you, from a single device. For example you build & configure a doorbell device, then every family member who owns the device can be connected to it and all of them receive notifications when someone is at their doorstep.

One Cricket module can be assigned to one developer only. You own it and no one can take it from you unless you Forget/Remove the device from your account. Only then another developer can assign your previously owned Cricket to their account only if you share with them the unique serial number.

The configuration is retrieved by Cricket after you press the built-in button on the module for at least 1 second. However Cricket needs to be paired to Wi-Fi with the internet access before it can fetch the configuration. See the Wi-Fi pairing section on how to connect Cricket to the internet.

Device registration

You configure Cricket remotely from Developer Portal from any browser either from PC or mobile.

You must register/login to Developer Portal to activate and configure modules in your account. Once you add Cricket (serial number) to your account no one else can do it unless you remove the device from your account. Only one developer account can control the module however there can be multiple users to receive data from the device. For that you need to make sure you keep the serial number safe and you do not give to anyone else.

After successful login / registration you need to click "Add new" device to activate your device in the system.

You need to use the unique serial number printed on a label stick on the back of Cricket.

NOTE: You must keep the serial number for yourself only. Do not share it with anyone else.

Forget / Remove device

Removing devices from the list is straightforward. Select the device you want to remove and click the “FORGET / REMOVE” link. What happens when you remove a device? The system simply cuts off the link between a device and your account. So the device becomes unassigned. The only reason you would like to remove a device is to pass it to another developer account. The configuration of the device is preserved. So when the device is registered again either by you or another developer the previous configuration is restored.

Device configuration

There are a few essential parameters which you need to configure to tailor your device functionality such as RTC, physical ports, temperature sensor, Webhooks, etc. This configuration must reflect how you assembled your device and which physical ports you connected peripherals / components to the Cricket module.

Configuration process is straight forward. Select a device from the list then set parameters presented in the middle panel. Remember to press the SAVE button after you finished. If you do not press SAVE all your changes will be lost. Below you can find a detailed description of all parameters and their values.

Parameter

Value

Description

Name

It is your arbitrary name of a device. The name is used in the dashboard to help you identify devices on your list.

RTC

(Real-Time Clock)

Off

Disable the  built-in Real-Time Clock. It disables periodical wake ups of your device. Your device, however, can still wake up from WAKE_UP port with a signal generated by an external component.

On

Enable the built-in Real-Time Clock. It enables Cricket to wake up automatically with your configured time interval specified by both “Units” and “Units Value” parameters (specified below).

For example, you can configure Cricket to wake up every 1 hour to evaluate a temperature sensor and send it to the internet.

Units

RTC configuration. Select one of the time units:

 > Seconds

 > Minutes

 > Hours

Units Value

RTC configuration. Specify time value expressed with a selected time unit (above). The system automatically validates values against a selected time unit. Below are the following valid ranges:

Hours: <0..23>

Minutes & Seconds: <0..59>

IO2

Off

Disable IO2 port, this when is disabled no value is read during sensory evaluation.

Analog In

Configure IO2 as analog input

Analog Divider

Defines analog input resolution value between 0 and 7

Digital In

Configures IO2 port as digital provide only 0 and 1 states

IO3

Reserved

Reserved

Battery Monitor

Off

Disable the built-in battery voltage monitor. If you are not going to report a battery level for users, it makes sense to keep this option Off.

On

Enable the built-in battery voltage monitor. Cricket reports the battery voltage level every time it connects to the internet. It makes sense to keep this option On only if it is essential for users to monitor the battery level.

Battery Divider

Configures resolution of the battery analog monitor which ranges from 0 to 7

Temperature Sensor

Off

Disable the built-in temperature sensor. Keep this option Off if you either do not require to report a temperature to device users or you attached an external temperature sensor to Cricket.

On

Enable the built-in temperature sensor on the Cricket module. Keep this option on if you want to send users an estimated temperature information. Reporting temperature can co-exist with other device functionalities. However if you require accurate temperature measurements you may need to use a dedicated external sensor, which you can attach to Cricket.

Temperature Moving Average

Defines moving average for built-in temperature sensor. The value defines a number of samples. If 0 the moving average is disabled.

“Force Updates” on

IO1 Wake Up

Off

Every time Cricket wakes up from the WAKE_UP pin it evaluates if property values have changed since the last evaluation. Only if they changed Cricket connects to the internet and sends data. Otherwise it powers off immediately.

On

Every time Cricket wakes up from the WAKE_UP pin all properties are sent to the internet regardless if values changed or not.

“Force Updates” on

RTC Wake Up

Off

Every time Cricket wakes up from RTC it evaluates if property values have changed since the last evaluation. Only if they changed Cricket connects to the internet and sends data. Otherwise it powers off immediately.

On

Every time the board wakes up from RTC all properties are sent to the Cloud regardless if values have changed or not.

“Post Events”

IO1 Wake Up

Defines URL address and payload for HTTP post request triggered when module is woken-up via  external WAKE_UP signal

RTC Wake Up

Defines URL address and payload for HTTP post request triggered when module is woken-up via internal RTC

IO2

Defines URL address and payload for HTTP post request triggered when  io2 signal changed

Temperature Sensor

Defines URL address and payload for HTTP post request triggered when temperature value changed

Battery Monitor

Defines URL address and payload for HTTP post request triggered when battery voltage changed

“MQTT Events”

Off

Disable MQTT communication channel

On

Enable MQTT communication channel

MQTT Broker

Select:

“Custom” - configure your MQTT broker

“Things On Edge” - use TOE MQTT broker

See MQTT Client configuration section how to receive data and events from either MQTT brokers.

MQTT Address

Option available when “Custom” MQTT broker is selected.

Defines MQTT server address and port. For example to configure CloudMQ your configuration may look like this:

m13.cloudmqtt.com:17605

Where:

m13.cloudmqtt.com - address of the server

17605 - port

MQTT User

Option available when “Custom” MQTT broker is selected.

Provide username for your MQTT broker account

MQTT Password

Option available when “Custom” MQTT broker is selected.

Provide password for your MQTT broker account

Retrieving configuration on your device

When you save configuration in Developer Portal you are prompted with the following message:

Now force Cricket to retrieve configuration by pressing the on-board button for 1 second. When Cricket wakes up and connects to the internet it fetches the latest configuration. However the portal’s web page is not refreshed automatically; you need to refresh it manually to see if the message disappears.

NOTE: At this point Cricket must be connected to the internet in order to fetch configuration. If you have not connected it yet, please go to the Connectivity section now.

If Cricket successfully fetched the latest configuration you should see the following message in the portal (remember to refresh the page).

If you still see the previous red message then the module did not fetch this configuration. There might be the following reasons why:

 > Cricket has not been connected / paired to Wi-Fi network yet

 > The Wi-Fi network does not have an internet access

Cricket fetches its latest configuration in the following scenarios:

 > Automatically whenever the Cricket wakes up and connects to the internet it fetches the latest config.

 > You can force Cricket to retrieve configuration by pressing the on-board button for 1 second.

Connectivity

All connectivity from Cricket is done over Wi-Fi network, which has access to the internet. It does not require any Bluetooth, NFC or any other connectivity. It is managed entirely from any Wi-Fi device with a web browser capability such as smartphone, tablet, laptop, smart TV, PC with Wi-Fi connector, etc.

It is important that you pair Cricket to a Wi-Fi network which has access to the internet. Cricket must connect to the Developer Portal service in order to receive its configuration, which is set by you.

Pair device to Wi-Fi network

In a few steps you connect Cricket to your Wi-Fi network as shown below:

1

Open Cricket’s private Wi-Fi hotspot: “toe_device

Press the button for 5 seconds until the LED is constantly lit.

NOTE: Make sure the LED is ON throughout the whole pairing process until you finish 3rd step. If it goes OFF then repeat this process starting from this 1st step.

2

Connect to “toe_device” Wi-Fi hotspot from any device mobile, laptop, ...

SSID: toe_device

No password required

Connect to “toe_device” hotspot from any device, which has Wi-Fi and web browsing capabilities such as laptop, smartphone, tablet, PC with Wi-Fi adapter, smart TV, etc.

3

Type your Wi-Fi network credentials on: http://192.168.4.1/index.html

Open Cricket’s private web page: http://192.168.4.1/index.html

Pass your Wi-Fi network credentials and click CONNECT

NOTE: make sure LED is still ON! When OFF repeat the steps from the beginning (Step 1.)

If SSID and Password are correct then after a few seconds the device connects to Wi-Fi and fetches the latest configuration from TOE Developer Portal. Then it powers down and the LED goes OFF as well.

You successfully connected your device to the internet! Now you can start playing with the configuration in Developer Portal and start receiving data and events on client devices: smartphone, laptop, PC, …

To find out more how you configure client devices to receive data & events go to the Communication channels section.

Pair from Mobile app

You can also download Things On Edge mobile app to make the binding process even easier. You can connect your device to the Wi-Fi network in a few clicks.

Android

Things On Edge App

Communication channels

This section provides more details on how you can receive data and events from Cricket on client devices such as phones, tablets, PCs, or any other services. Also how you can integrate your devices with the IOT ecosystem of apps and services available on the internet.

You can configure two communication channels:

 > MQTT - for 1 to many clients direct communication and low latency

 > HTTP POST request (a.k.a. Webhooks)

You can configure Cricket to send data and events directly to your preferred services either MQTT or Webhooks (i.e. IFTTT, ...) without involving Things On Edge service.

A high level routing overview of how Cricket sends data over the internet is shown below:

The above mentioned communication channels are explained in more details in the following sections.

MQTT

Cricket has a built-in native MQTT support which also comes with a FREE Cloud service (TOE MQTT broker) to maintain reliable connectivity, low latency and low power consumption. However you can also configure Cricket to send data and events directly to other 3rdparty MQTT brokers.

Cricket module sends MQTT messages via configured MQTT broker. You can subscribe / connect any client device directly to this service. Every Cricket comes with a unique serial number which is used for authentication credentials with Things On Edge MQTT broker i.e. username & password.

The data and events are sent on separate MQTT topics for each Cricket. This means that you do not require to use advanced filters to extract data from messages. They can be simply read directly from received messages. Below you can find more information on what MQTT topics you can subscribe from client devices.

MQTT client configuration

You can configure Cricket to use other 3rd party MQTT providers. All you need is a server address, port and user credentials (user & password). Then you can configure your selected MQTT broker from within the Developer Portal. Then your client devices must be configured with the same or other associated credentials. Here is an example how to configure Cricket to send messages directly to CloudMQTT on 17605 port. If you use the same credentials on your client device then you can receive data on your device.

In order to connect to Things On Edge MQTT broker you need to use the following server address, port and credentials as every Cricket comes with a private account:

Server address:

mqtt.thingsonedge.com

Port:

1883

Username:

SERIAL

Password:

SERIAL

SERIAL - is a unique serial number, which is printed on the back of Cricket’s module as shown below

MQTT subscribe topics for clients

Cricket publishes (sends) data and events on topics listed below. All topics has the following format:

/  SERIAL   /   PARAM

Where:

SERIAL:

as explained above is Cricket’s unique serial number

PARAM:

is a module property/sensor type (see the table below)

PARAM

Format

Unit

Range

Example

Description

temp

dd.d

Celsuis

−40°C to +110°C

12.5

Temperature value from built-in Cricket’s temperature sensor

batt

ddd

Decimal

0 to 255

124

Current battery voltage level represented as 8bits decimal value

io2

ddd

Decimal

0 to 255

100

Current level on the IO2 port. If you choose IO2 as digital than the value is either 0 or 1

io1_wake_up

d

Decimal

0 or 1

1

The payload value of that topic is 1 if the module was woken up by a WAKE_UP pin otherwise is 0. This message is only published if either WAKE_UP is triggered or "Force Updates" > “IO1 Wake Up” is enabled in the module configuration.

rtc_wake_up

d

Decimal

0 or 1

1

The payload value of that topic is 1 if the module was woken up by internal RTC otherwise is 0. This message is only published if either RTC wake-up is triggered or "Force Updates” on “RTC Wake Up” is enabled in the module configuration.

cnt_wake_up

ddd

Decimal

0 to 2147483647

11

This is an internal counter representing a number of wake ups of Cricket

cnt_published

ddd

Decimal

0 to 2147483647

12

This is an internal counter representing a number of messages sent to the internet by Cricket

d - a single decimal digit

Example of subscribe topics for Cricket with 1234566789 serial number:

/1234566789/temp

the subscribe topic to monitor a temperature from the “1234566789” device

/1234566789/batt

the subscribe topic to monitor a battery level of the “1234566789” device

HTTP POST Requests

HTTP POST request is another way Cricket can send data to desirable client servers or services i.e. IFTTT, Web services, Mobile IoT services and the like.

You can configure the address and payload for all events, listed below in the table, from Developer Portal. For each event there is a corresponding HTTP configuration and Data fields.

Event name

Description

“IO1 Wake Up”

This event is triggered every time when Cricket wakes up via an external WAKE_UP pin.

“RTC Wake Up”

This event is triggered every time when Cricket wakes up via internal RTC.

“IO2”

The event is triggered every time when input, either digital or analog, value changes.

“Temperature Sensor”

The event is triggered every time when temperature changes.

“Battery Monitor”

The event is triggered every time when battery voltage changes. The change is evaluated after applying the divider value.

You can also use this HTTP POST method to send your customised payload. The content is marked as json in the header and thus data should be guarded by {} as a valid JSON payload. Some web services are more relaxed in checking payload headers. You might be able to use a non-JSON payload but it depends on that service requirement.

You can define payload that Cricket can dynamically modify and insert its current parameters e.g. current temperature or IO values. You can do it by inserting corresponding tags to event names in the payload definition.

In order to do that you Insert a tag into payload with a preceding # character. Once Cricket finds such tags in payload they are replaced with the current corresponding values to these tags. The list of available tags is shown in the table below.

Tag

Description

#io1_wake_up

This tag is replaced by value 0 or 1. If the module was woken-up via external WAKE_UP pin this value is 1 otherwise 0.

#rtc_wake_up

This tag is replaced by value 0 or 1. If the module was woken-up via internal RTC interrupt this value is 1 otherwise 0.

#io2

This tag is replaced by the current value on IO2 port.

#temp

This tag is replaced by the current tempere after averaging if enabled.

#batt

Thi tag is replaced by current battery value after applying a divider if enabled.

Example of your payload with tags:

>>>

Payload processed and sent by Cricket

{"value1":"#batt","value2":"#temp"}

{"value1":"120","value2":"22.0"}

There are no limits of how many tags you can define in your data pattern (payload). You can also duplicate tags in the same data pattern.

Examples

HTTP POST request example: A button for sending emails over IFTTT

In this example we show how you can configure Cricket to send email notifications with IFTTT when voltage is raised on the WAKE_UP port by using a button.

First you need to configure IFTTT service with Webhook

  1. Go to: https://ifttt.com/
  2. Login or register
  3. Click Create from User / Account menu (top right corner)
  4. Click + to create new source event
  5. Select Webhooks service
  6. Click Continue
  7. Click Receive a web request (on the left hand side)
  8. Create event name e.g. email_button
  9. The source event should be set-up now, click + after Then event
  10. Search email service
  11. Change subject and body of the email accordingly
  12. Click Finish

Now you need to get a HTTP address to which you can post events from Cricket. Search for Webhooks service and click on the document in the right up corner.

Copy web links under "Make a POST or GET web request to:"

Now you need to go to TOE Developer Portal and set the following configuration for the device:

Parameter

Value

“Post Events” > “IO1 Wake Up” > “URL”

Copy / paste the link from Webhooks and:

  1. replace https to http
  2. replace event to email_button

The link should look similar to the one shown below:

http://maker.ifttt.com/trigger/email_button/with/key/
hfNIx8SKn_..._YW3xx5yFw5MGD

“Post Events” > “IO1 Wake Up” > “Data”

Leave it empty

“Force Updates” > “IO1 Wake Up”

On

“Force Updates” > “RTC Wake Up”

Off

“RTC”

Off

“IO2”

Off

“IO3”

Off

“Battery Monitor”

Off

“Temperature Sensor”

Off

Do not forget to press the button on the Cricket module for 1 second to fetch this configuration.

Now whenever you press the attached button to Cricket’s WAKE_UP pin you receive an email.

HTTP POST request with payload tags example

This example shows how you can configure Cricket to report a temperature every minute to your IFTTT service (for example log temperature into a Google spreadsheet).

Open Developer Portal, select your device and set the following configuration:

Parameter

Value

“Post Events” > “RTC Wake Up” > “URL”

http://maker.ifttt.com/trigge…. [you must copy paste your url here]

“Post Events” > “RTC Wake Up” > “Data”

{“value1”:“#batt”, “value2”:“#temp”}

“RTC”

On

“RTC” > “RTC Units”

Minutes

“RTC” > “RTC Units Value”

1

“Battery Monitor”

On

“Temperature Sensor”

On

Do not forget to press the button on the Cricket module for 1 second to fetch this configuration. Now Cricket wakes up every minute and sends both the temperature and battery level to the IFTTT service.

The payload message sent by Cricket, for this example, looks like this:

{“value1” : “120”, “value2” : “22.0”}

If you wish you can calculate back the battery voltage on the client side with the following formula:

Batt_vcc = (3.5 / 256) * 120 = 1.64V

MQTT Example: use Mobile app

You can use any preferred MQTT client on your mobile. We recommend to start playing either with IoT OnOff (for both Android and iOS) or IoT MQTT Panel (Android only) which is shown as an example below.

Let's use the IoT MQTT Panel application as an example to demonstrate how to receive and visualise data from Cricket by using native TOE MQTT broker (mqtt.thingsonedge.com).

  1. Download and install IoT MQTT Panel
  2. Configure a server connection with the following details:
    Server / Broker IP address:
    mqtt.thingsonedge.com
    Port number:
    1883
    Network protocol:
    TCP

  1. Add device e.g. "Temperature"

  1. Goto advanced options:
    Username:
    your_cricket_serial_number
    Password:
    your_cricket_serial_number
    Connect automatically:
    YES

  1. Press the Create button

  1. Press ADD PANEL

  1. Select: Line Graph

  1. Set the details for graph 1 to read data from sensor (from the Cricket IO2 port)
    Panel name: e.g.
    Temperature
    Topic for graph 1:
    /your_cricket_serial_number/temp
    Show area:
    YES
    Show points:
    YES

For more information please refer to the attached screenshots from IoT MQTT Panel below.

Complete examples

Below you can find a few examples with a full step by step guidance on how Things On Edge technology is applied.

IoT Moisture Sensor - based on MQTT

IoT Button with IFTTT integration

IoT Motion Sensor with Email alerts

Home Assistant integration


thingsonedge.com

Copyright © 2020 Things On Edge Limited.

All rights reserved.

Cambridge, UK