UnaShield V2S + Antenna

SGD65.00

UnaShield V2S + Antenna

SGD65.00

 

DESCRIPTION

UnaShield is an Arduino Shield with a Sigfox transceiver module that is compatible with Arduino Uno R3 and other Arduino-based development boards. It uses Sigfox-certified WISOL or Radiocrafts modules to support all RCZs (Radio Configuration Zones).

  • RCZ1: Europe, Iran, Oman, South Africa
  • RCZ2: Brazil, Mexico, USA
  • RCZ3: Japan
  • RCZ4: Argentina, Australia, Colombia, Hong Kong, New Zealand, Singapore, Taiwan


There are 2 versions of the UnaShield:

  • UnaShield V2S: Based on Sigfox module by WISOL. Includes onboard sensors for temperature, humidity, air pressure, accelerometer and two ports for connecting Grove sensors.
  • UnaShield V1: Based on Sigfox module by Radiocrafts.

 

The UnaBiz team has built an Arduino library for the UnaShield, the source code may be found here: https://github.com/UnaBiz/unabiz-arduino. This page explains how to use the Arduino library to send Sigfox messages with the UnaShield.

Features V1A
(20161128)
V2
(20170325)
V2S
(20170107)
V2S
(20170325)
Sigfox Module Radiocrafts RC1692HP-SIG
WISOL WSSFM10R
Sigfox RCZ 2 / 4 1 / 2 / 3 / 4 1 / 2 / 3 / 4 1 / 2 / 3 / 4
Sensor Accelerometer (MMA8451Q)
Temperature Sensor (BME280)
Pressure Sensor (BME280)
Push Button
Peripheral Connection Digital Grove (I2C)
Analog Grove
LED Power Indication
General Indication
Module Status Monitor
Antenna Matching Circuit


Schematics

UnaShield V1A:


UnaShield V2S:


UnaShield V2 / V2S (20170325):


Pin Assignment

Arduino Pins UnaShield V1A UnaShield V2 / V2S Description
Reserved NC NC Reserved
IOREF 5V 5V 5V Power Source from Arduino platform
RESET RESET RESET Reset Arduino MCU & Sigfox Module;Low active
3V3 3V3 3V3 3V3 Power Source from Arduino platform
5V 5V 5V 5V Power Source from Arduino platform
GND GND GND Grounding & power/signal reference level
GND GND GND Grounding & power/signal reference level
VIN NC NC Extra power source input of Arduino platform
A0 NC NC Analog Pin-0
A1 NC NC Analog Pin-1
A2 NC A2 Analog Pin-2;Grove Connector #2
A3 NC A3 Analog Pin-3;Grove Connector #2
A4 NC I2C-SDA Analog Pin-4;Grove Connector #1
A5 NC I2C-SCL Analog Pin-5;Grove Connector #1
SCL NC NC Branch of A5 (I2C-SCL)
SDA NC NC Branch of A4 (I2C-SDA)
AREF NC NC Reference level input for Arduino MCU
GND GND GND Grounding & power/signal reference level
D13 NC NC Digital Pin-13
D12 NC NC Digital Pin-12
D11 NC NC Digital Pin-11
D10 NC NC Digital Pin-10
D9 NC Red-LED User Programmable Red LED
D8 NC Green-LED User Programmable Green LED
D7 NC Wakeup Wakeup onboard module from deep sleep mode
D6 NC Button Push button;Push to low signal level
D5 UART-RX UART-RX UART receiving pin
D4 UART-TX UART-TX UART transmitting pin
D3 NC INT2 Interrupt#2 of Bosch sensor (BME280)
D2 NC INT1 Interrupt#1 of Bosch sensor (BME280)
D1 NC NC Digital Pin-1
D0 NC NC Digital Pin-0

 

The five pins marked by * are required for proper operation of the onboard Sigfox module. Even though UnaShield is designed for Arduino Uno R3, the UnaShield can be integrated with another device as a Sigfox network adapter if these essential five pins are properly connected.
The onboard Sigfox module works with DC 3V3 power. All the Arduino pins used by the UnaShield are connected to a level-shifter to ensure that the pin voltage is always fixed at 3V3.


Features and Functions

    1. SMA Connector
      To prevent damage to the onboard Sigfox module, always connect the antenna before powering up the UnaShield and before sending any Sigfox messages. The SMA (SubMiniature version A) Connector is used for connecting the provided coaxial RF antenna to the UnaShield.

    2. Sigfox Module
      UnaShield V1(A) embeds a Radiocrafts Sigfox module RC1692HP-SIG, certified for RCZ2 and RCZ4; UnaShield V2 / V2S uses a WISOL Sigfox module in the WSSFM10R Series, certified for all four RCZs. The Sigfox modules may be controlled via the UART interface with serial terminal commands (similar to the AT Command Format used by modems).
      UnaShield V1A UnaShield V2 / V2S
      Radiocrafts RC1692HP-SIG WISOL WSSFM10R
      For RCZ2 and 4 For all RCZs: RCZ1, 2, 3 and 4
    3. Arduino Uno Standard Header
      UnaShield has four Arduino standard headers (pin connectors): one 6-pin header, two 8-pin headers, and one 10-pin header. Not all Arduino pins are used by the UnaShield, some Arduino pins are passed through unmodified by UnaShield.

      You may use the unused Arduino pins to connect other sensors and components. However take note that the voltage level of Arduino Uno R3 is 5V, which may not be directly usable by some sensors or components.

      For the details of each Arduino Uno pin assignment and definition, please check the Arduino official website: https://www.arduino.cc/en/Main/ArduinoBoardUno

    4. Push Button (UnaShield V2 / V2S only)
      A Push Button (tact switch) is connected to the D6 Digital Input pin of the Arduino Uno. The button may be programmed in Arduino sketches to trigger certain functions when pressed.

    5. Grove Connector (UnaShield V2 / V2S only)
      UnaShield V2S is equipped with two Grove Connectors, a standard 4-pin connector for Grove sensors. You may connect sensors or components with Grove interfaces to extend the capabilities of the Arduino device.

      Grove Connector #1:Connected to Arduino I2C Digital Interface (SCL and SDA)
      Grove Connector #2:Connected to Arduino Analog Input/Output interface (A2 and A3)
      The onboard Grove connectors support two voltage levels: 3V3 or 5V. Select the Grove voltage through jumper J204.

      Floating 5V 3.3V (Default)
      Jumper J204
    6. LED Indicator and Manual Switches (UnaShield V2 / V2S only)
      Eight onboard LEDs are used to show the status of the UnaShield. The LEDs may be disabled through the jumpers J201, J202 and J203.

      Jumper J201 – Controls the Status LEDs of the WISOL module (TX, RX, CPU & RF)
      Disabled Enabled (Default)
      Jumper J201

      Jumper J202 – Controls the Grove Voltage Level LED (3V3 or 5V)
      Disabled Enabled (Default)
      Jumper J202

      Jumper J203 – Controls the User-Programmable LEDs (D8, D9)
      Disabled Enabled (Default)
      Jumper J203
    7. I2C Interface (UnaShield V2 / V2S only)
      I2C (Inter-Integrated Circuit) is a two-wire, bidirectional protocol for connecting multiple sensors and components on the same pair of wires.

      The I2C interface requires two pins: data line (SDA) and clock line (SCK). I2C works in the daisy-chain configuration, so one master device can communicate with more than one slave device, just by selecting the unique I2C address of the slave device.

      The UnaShield accelerometer sensor and temperature / humidity / pressure sensor are connected to the I2C bus by unique I2C addresses, which are preset in the sensor hardware.

      NXP Accelerometer (G-Sensor) – MMA8451Q
      SA0 I2C Address Default
      LOW 0x1C
      HIGH 0x1D

      BOSCH Temperature / Humidity / Pressure Sensor – BME280
      SD0 I2C Address Default
      LOW 0x76
      HIGH 0x77

      Grove Connector #1
      Grove Connector #1 is also connected to the I2C bus. The sensor or component connected through Grove Connector #1 must use an I2C address that is distinct from the above I2C addresses, to avoid address conflict.

 

Activating the UnaShield

To activate the UnaShield and get access to Sigfox Backend, please refer to: https://github.com/UnaBiz/unabiz-arduino/wiki/Activation


Declaring the transceiver

To declare a transceiver object for sending Sigfox messages:

#include "SIGFOX.h"  //  Include the unabiz-arduino library.
static const String device = "g88pi";  //  Set this to your device name if you're using UnaBiz Emulator.
static const bool useEmulator = false;  //  Set to true if using UnaBiz Emulator.
static const bool echo = true;  //  Set to true if the Sigfox library should display the executed commands.
static const Country country = COUNTRY_SG;  //  Set this to your country to configure the Sigfox transmission frequencies.
static UnaShieldV2S transceiver(country, useEmulator, device, echo);

If you’re using UnaShield V1, change UnaShieldV2S to UnaShieldV1.

Change COUNTRY_SG to your country code (e.g. COUNTRY_AU, COUNTRY_NZ). This sets the transceiver object to use the Sigfox frequencies for your country.

useEmulator should always be set to false. If you are connecting the UnaShield V2S to the SNEK emulator, set useEmulator to true. You will not be able to connect the UnaShield to the actual Sigfox network when useEmulator is set to true.

The following sections explain how to use the transceiver.sendMessage method to send a raw Sigfox message, and the Message class to send a structured message.


Initialising the transceiver

Initialise the transceiver object in the setup function before sending any messages:

if (!transceiver.begin()) stop(F("Unable to init Sigfox module, may be missing"));

The message “Unable to init…” is displayed if the transceiver could not be initialised, e.g. when the UnaShield is not connected to the Arduino board. The F(…) function stores the message string into flash memory instead of highly-limited static RAM, to support larger Arduino sketches.


Sending a raw message

To send a raw message of up to 12 bytes:

transceiver.sendMessage("0102030405060708090a0b0c");  //  Send raw message.
delay(10000);  //  Wait 10 seconds.

This sends a Sigfox message containing the bytes “0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c”.

Note that we may not send two messages within 10 seconds due to the Sigfox rate limit. Each Sigfox device may send up to 140 messages within a 24-hour period.

 

Sending a text message

To send a message containing a text string of up to 12 ASCII characters:

transceiver.sendString("123456789abc");  //  Send text message.
delay(10000);  //  Wait 10 seconds.

This sends a Sigfox message containing the bytes 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x61 0x62 0x63. This is equivalent to calling:

transceiver.sendMessage("313233343536373839616263");  //  Send raw message
delay(10000);  //  Wait 10 seconds.

Helper methods are provided in the transceiver object to help encode various Arduino types into hexadecimal strings for sending via sendMessage:

String encode1 = transceiver.toHex(0x1234);  //  Returns "3412" (least significant byte first).
String encode2 = transceiver.toHex(1.23);  //  Returns "a4709d3f" (IEEE 574 float encoding, least significant byte first).
transceiver.sendMessage(encode1 + encode2);  //  Send the 6-byte message "3412a4709d3f".

//  Second argument is the number of characters to encode.
String encode3 = transceiver.toHex("123456789abc", 12)  //  Returns "313233343536373839616263".
transceiver.sendMessage(encode3);  //  Send the 12-byte message "313233343536373839616263".

 

Sending a structured message

The unabiz-arduino library includes a Message class that allows us to send structured messages containing up to 3 data fields, packed into a 12-byte Sigfox message. The Message class is used like this:

Message msg(transceiver);  //  Will contain the structured sensor data.
msg.addField("ctr", counter);  //  4 bytes for the counter.
msg.addField("tmp", temperature);  //  4 bytes for the temperature.
msg.addField("vlt", voltage);  //  4 bytes for the voltage.
//  Total 12 bytes out of 12 bytes used.
if (msg.send()) {  //  Send the message.
  successCount++;  //  If successful, count the message sent successfully.
}
delay(10000);  //  Wait 10 seconds.

Each addField(name, value) method adds a data field to the message:

  • name: Name of data field, up to 3 lowercase letters or digits allowed
  • value: Value of data field of type int, float or String (up to 3 characters)


This transmits an encoded message that looks like 920e5a00b051680194597b00. The 12-byte encoded message contains the field names ctr, tmp, vlt as well as the field values. To decode the message at the server side, refer to the next section.


Decoding a structured message

To decode a structured message at the server, refer to the Node.js / JavaScript function decodeMessage here: https://github.com/UnaBiz/sigfox-gcloud/blob/master/decodeStructuredMessage/structuredMessage.js

At UnaBiz we call decodeMessage to decode the structured messages when tracing messages via Slack:

The Structured Message Format is described in the section “Format of structured message” below.


Sending a Sigfox Custom Payload message

If you don’t wish to use the above Structured Message Format and perform message decoding in your cloud, you may use the Sigfox Custom Payload format to allow Sigfox to decode simple message formats and pass the decoded fields in the Sigfox callback. Note that each Sigfox Message Type is allowed to have only 1 Custom Payload format.

Refer to these documents for details:


Getting the downlink response from Sigfox

Refer to https://github.com/UnaBiz/unabiz-arduino/wiki/Downlink


Checking messages sent by the UnaShield

The Sigfox Backend Portal enables us to view the messages received by Sigfox from the UnaShield.

Log on to the Sigfox Backend Portal at http://backend.sigfox.com


Processing messages sent by the UnaShield

To process the messages sent by the UnaShield, we need to provide a server with a public address. The Sigfox cloud will send a HTTP POST request to our server whenever Sigfox receives a message from the UnaShield. UnaBiz has provided an open-source server application for processing Sigfox messages in Google Cloud: https://www.npmjs.com/package/sigfox-gcloud

To use your own server, follow the instructions above to configure the Sigfox callback URL for your device type. Enter your callback URL instead of the one shown in the instructions. For more details please refer to this page in the Sigfox backend: https://backend.sigfox.com/apidocs/callback


Changes from UnaShieldV1 interface to UnaShieldV2S

An Arduino sketch built for UnaShield V1 (Radiocrafts) can run on UnaShield V2S (Wisol) with virtually no changes. The only change to the interface is for

bool Wisol::getTemperature(float &temperature)

Previously it was int, now it’s float. The class UnaShieldV2S is an alias to the Wisol class.

 

Demo sketches for UnaShield V2S sensors

The following Arduino sketches show how we may access the other sensors on the UnaShield V2S:

 

Getting the Sigfox Device ID and PAC (Porting Authorization Code)

When the above demo code runs, the Arduino Serial Monitor will show the Sigfox Device ID and PAC like this:

- Wisol.getID: returned id=002BEDB4, pac=C53D6575A5DA0000
- Sigfox ID = 002BEDB4
- PAC = C53D6575A5DA0000

The Device ID and PAC will be used to activate the UnaShield with the Sigfox Operator. Note that the PAC is only valid for one use only. Once a device has been activated with the PAC, the device cannot be activated again on a different Sigfox Operator with the same PAC.

 

Support for LightBlue Bean+

The LightBlue Bean+ by Punch Through is a tiny Arduino-compatible board with built-in:

  1. Lithium battery (600mAh)
  2. Accelerometer
  3. Temperature sensor
  4. Two ports for Grove sensors
  5. RGB LED
  6. And Bluetooth 4.0, supporting iBeacon and Arduino flashing / log access over Bluetooth


By adding the UnaShield to the Bean+, you create a self-powered sensing device that can send sensor data to the Sigfox cloud for many days on a single charge

Check out https://github.com/UnaBiz/unabiz-arduino/wiki/Bean


Support for Raspberry Pi and other devices 

This article explains the pins on the UnaShield that should be connected for proper operation. When the send/receive, power and ground pins are connected to the Raspberry Pi or other devices, you should be able to send commands to the Wisol or Radiocrafts module via the Serial / UART interface. https://github.com/UnaBiz/unabiz-arduino/wiki/Bean

Also check these articles for compatibility information: Arduino Mega / Leonardo / Micro


Format of structured message

The structured message format was created such that all 12 bytes in a Sigfox message could be used to transmit 3 fields efficiently, including a 3-letter field name (e.g. ctr). The field name was included so that any generic IoT platform (e.g. Amazon Web Services IoT) could decode the fields and refer to the fields by name for IoT rules, alerts, dashboards and other types of IoT data processing.


Each structured message contains 1 to 3 data fields of 4 bytes each:

Structured Message: (12 bytes)

Data Field 1 (mandatory) Data Field 2 (optional) Data Field 3 (optional)
4 bytes 4 bytes 4 bytes


Each data field contains 2 bytes for the field name (e.g. ctr), followed by 2 bytes for the field value (int, float or String):

Data Field: (4 bytes)

Field Name Field Value
2 bytes 2 bytes


Field name consists of 1 to 3 lowercase letters or digits, packed as 5 bits each.

Field Name / String Value Encoding: (2 bytes)

First Letter/Digit Second Letter/Digit Third Letter/Digit Unused
5 bits 5 bits 5 bits 1 bit


A letter/digit is mapped to 5 bits as follows:

Letter/Digit Encoding: (5 bits)

Letter/Digit Value
End of field 0
a 1
b 2
... ...
z 26
0 27
1 28
... ...
9 36

 

Field value is encoded into 2 bytes as follows:

Field Value: (2 bytes)

Field Type Encoding
int Multiply value by 10 and encode as 16-bit integer
float Multiply value by 10 and encode as 16-bit integer
String Use Field Name / String Value Encoding above

The Arduino code for encoding a structured message may be found here: https://github.com/UnaBiz/unabiz-arduino/blob/master/Message.cpp