Software
Last updated
Last updated
The Waspmote device communicates with the Sigfox module via UART. So different commands are sent from the microcontroller unit to the module so as to perform different tasks.
The files related to the Sigfox libraries are:
It is mandatory to include the Sigfox library when using this module. So the following line must be added at the beginning of the code:
To start using the Waspmote Sigfox library, an object from the 'WaspSigfox' class must be created. This object, called Sigfox, is already created by default inside Waspmote Sigfox library. It will be used through this guide to show how Waspmote works.
When using the class constructor, all variables are initialized to a default value.
The API constants used in functions are:
The variables used inside functions and Waspmote codes are:
Through this guide there are lots of examples of using functions. In these examples, API functions are called to execute the commands, storing in their related variables the parameter value in each case. The functions are called using the predefined object Sigfox.
All public functions return three possible values:
SIGFOX_ANSWER_OK = 0
SIGFOX_ANSWER_ERROR = 1
SIGFOX_NO_ANSWER = 2
Remember you need to purchase Sigfox connectivity to be able to use the Sigfox network.
The ON() function allows the user to switch on the Sigfox module, open the MCU UART for communicating with the module and automatically enter into command mode. After this step the module will be able to receive more commands to configure it or send packets to the Sigfox network. It is necessary to indicate the socket that it is being used: SOCKET0 or SOCKET1.
Example of use for SOCKET0:
The OFF() function allows the user to switch off the Sigfox module and close the UART. This function must be called in order to keep battery level when the module is not going to be managed. It is necessary to indicate the socket that it is being used: SOCKET0 or SOCKET1.
Example of use for SOCKET0:
The getID() function allows the user to get the Sigfox module identifier. This ID is a variable 4- to 8-digit hexadecimal number. The identifier is stored in the _id attribute.
Example of use:
Related variable:
Sigfox._id → Stores the module's identifier
Example of getting Sigfox module identifier:
The send() function allows the user to send Sigfox packets to the network. Sigfox packets maximum payload is 12 bytes. So the user must fit to this restriction when sending new packets.
There are two sending function prototypes. They are explained below:
Send packets defined as strings
The next function shows how to send packets defined as a string. So every single byte in the packet must be previously converted into the ASCII representation. In the next example, it is possible to see how to send a 12-byte packet composed of 24 hexadecimal digits.
Example of use:
Example of sending a packet as string:
Send packets defined as array of bytes
On the other hand, the next function shows how to send packets defined as array of bytes. It will be necessary to indicate both pointer to the array and the length of the array. This function prototype can be useful for the user if they prefer to define their own packet formats.
Example of use:
Example of sending a packet as array of bytes:
The sendACK() function allows the user to send Sigfox packets to the network acknowledging the packet reception. So it is possible to know when a transmission went well for sure. The user can configure the “device type” in the Sigfox back-end in order to acknowledge the packet. It is even possible to send back information from the server to the module within a downlink transmission when the acknowledge is performed. In the case downlink transmission are set for a specific device, after receiving the downlink data the module answers the server with another acknowledgment which is free of charge. Please, refer to “Sigfox Back-End” section in order to know more.
In the case of using acknowledgements, the transmission of packets takes much longer. The user must keep in mind that ACKs are sent once the packet is received by the Sigfox cloud. So, transmissions processes can take longer than 30 seconds. This will increase the energy consumption of the system. In this case, Sigfox packets also have a maximum payload of 12 bytes. So the user must fit to this restriction when sending new packets.
There are two sending function prototypes. They are explained below:
Send packets defined as strings with ACK
The next function shows how to send packets defined as a string waiting for an ACK. So every single byte in the packet must be previously converted into the ASCII representation. In the next example, it is possible to see how to send a 12-byte packet composed of 24 hexadecimal digits.
Example of use:
Example of sending a packet as string with ACK:
Send packets defined as array of bytes with ACK
On the other hand, the next function shows how to send packets defined as array of bytes waiting for an ACK. It will be necessary to indicate both pointer to the array and the length of the array. This function prototype can be useful for the user if they prefer to define their own packet formats.
Example of use:
Example of sending packet as array of bytes with ACK:
The sendKeepAlive() function allows the user to send a Keep-Alive message to the network. This can be useful to perform daily heart beats, and this way ensure the system will work when most needed in the event of an alarm.
Example of use:
Example of sending a keep-alive:
The setPower() function allows the user to set the RF power level in dBm. Sigfox EU power range is from 0 to 14 dBm. The default value is 14 dBm. Remember that you should not transmit at more than 14 dBm in Europe, due to ETSI regulation. Sigfox US power levels are: 15, 20, 22, 23 and 24. The default value is 24 dBm.
Example of use:
The getPower() function allows the user to query the power level.
Example of use:
Related variable:
Sigfox._power → Stores the module's power level
Example of setting and getting power level:
The testTransmit() function allows the user to send a TX Sigfox test to the network. The function will ask for three different inputs:
Count: From 0 to 65535, count of Sigfox test RF messages
Period: From 1 to 255, period in seconds between Sigfox test RF messages
Channel: From 0 to 180 or 220 to 400 or -1 (random channel). Channel number to use for Sigfox test RF messages. Channels have a fixed 100 Hz bandwidth, starting at 868.180 MHz for channel 0, ending at 868.198 MHz for channel 180, restarting at 868.202 MHz for channel 220 and ending at 868.220 MHz for channel 400.
Example of use:
Example of TX Sigfox test:
The showFirmware() function allows the user to print the Firmware version via USB port. The result is stored in the attribute _firmware, which is a buffer of the class. The function displays the library version number as follows: SOFTxxxx, where the “xxxx” stands for the version number.
Example of use:
Example of showing the firmware version:
This feature is only available for the Sigfox US module and the Sigfox APAC / LATAM module.
The setRegionRC4() function allows the user to configure the module to work in the RC4 zone. With the setRegionRC2() function the user can configure the module back to the RC2 zone. These functions configure internal variables of the module to the necessary parameters to work in different Sigfox radio configuration zones.
Example of use:
Example of use:
Besides using the Sigfox network, it is possible to set up a LAN network between several modules so as to establish P2P communications.
This feature is only available for the Sigfox EU module (Europe version). The US version module (Sigfox US) can only transmit frames with the Sigfox mode.
The LAN network operates using time division duplexing (TDD), where the device alternately transmits and receives data packets over the same radio channel. Thus, P2P connections can be made between several modules. If only one receiver is used and several modules transmit data, then a star topology network is created.
The frequency band used for transmissions is the ISM 869 MHz radio band (868.0 to 869.7 MHz). The devices use a single 25 kHz narrow-band channel to transmit data at 9600 bps using a GFSK modulation.
The transmit power can be configured using the proper function, in order to reduce the power consumption or increase the radio range when required.
The maximum payload is 17 bytes. The packets are acknowledged by the receiver. If this acknowledgement is not received within 2 seconds, the message frame is resent up to 2 times before giving up.
Regarding the addressing of packets, each module is assigned with a logic 24-bit logic address and a corresponding 24-bit address mask. The logic address is transmitted into the RF frames that are sent and matched by the receiver after applying the address mask to it. The default null address and full address mask (all bits set to 1) ensure that receiving is enabled by default. However, the recommended setup is to have a full address mask (all bits set to 1) for the transmitter and a partial address mask (not all bits are set to 1) for the receiver, both devices having a common address field (i.e. same “subnet”) over the partial address mask bits. This addressing scheme provides a way for transmitters to access the receiver when they are using the same “subnet”, and for the receiver a way to acknowledge a particular frame that has been received from the original transmitter only.
Here is an example for a 4-bit subnet mask:
Receiver: Address 0x5ED709, Mask 0xF00000
Transmitter: Address 0x55C344, Mask 0xFFFFFF
The setAddressLAN() function allows the user to set the module's 24-bit LAN address. The getAddressLAN() function allows the user to query the module's LAN address. The attribute _address permits to access to the address settings of the module. The range of this variable is from 0x000000 to 0xFFFFFF. The default value is 0x000000.
Example of use:
Related variable:
Sigfox._address → Stores the module's LAN address
Example of configuring the LAN settings in the module:
The setMask() function allows the user to set the module's 24-bit address mask. The getMask() function allows the user to query the module's address mask. The attribute _mask permits to access to the mask settings of the module. The range of this variable is from 0x000000 to 0xFFFFFF. The default value is 0xFFFFFF.
Example of use:
Related variable:
Sigfox._mask → Stores the module's LAN mask
Example of configuring the LAN settings in the module:
The setFrequency() function allows the user to set the module's frequency value. The getFrequency() function allows the user to query the module's frequency value. The attribute _frequency permits to access to the frequency settings of the module in Hz units. The range of this variable is from 868000000 to 869700000. The default value is 869312500.
Example of use:
Related variable:
Sigfox._frequency → Stores the module's LAN mask
Example of configuring the LAN settings in the module:
The setPowerLAN() function allows the user to set the module's power level for LAN networks. The getPowerLAN() function allows the user to query the module's power level. The attribute _powerLAN permits to access to the power level settings of the module in dBm units. The range of this variable is from -35 to 14. The default value is 14.
Example of use:
Related variable:
Sigfox._powerLAN → Stores the module's LAN mask
Example of configuring the LAN settings in the module:
The sendLAN() function allows the user to send LAN packets to another module. The maximum payload size for LAN packets is 17 bytes. So the user must fit to this restriction when sending new packets.
There are two sending function prototypes. They are explained below:
Send packets defined as strings
The next function shows how to send packets defined as a string. So every single byte in the packet must be previously converted into the ASCII representation. In the next example, it is shown how to send a 17-byte packet composed of 34 hexadecimal digits.
Example of use:
Example of sending a packet as string:
Send packets defined as array of bytes
On the other hand, the next function shows how to send packets defined as array of bytes. It will be necessary to indicate both pointer to the array and the length of the array.
Example of use:
Example of sending a packet as array of bytes:
Receive RF messages in single-packet mode
The receive() function allows the user to wait for an incoming LAN packet. The period of time to wait is indicated as input in seconds units.
If a packet is received within the specified timeout, the function returns with ok response and the packet contents are stored in _packet structure. The incoming packet will always be a 17-byte length message (represented as a string), independently of the number of bytes sent. If the packet length is less than the maximum size, then the received message is always padded with “00” bytes. If no packet arrives within the given timeout, the function returns with error response.
Anyway, the user must keep in mind that after calling the receiving function, the module exits the receiving mode regardless of the execution response of the function.
Example of use:
Related variable:
Sigfox._packet → Stores the received packet inside this string of 35 bytes
Example of receiving a packet as string:
The setMultiPacket() function allows the user to set up the module for continuous receiving mode. In any moment, a new packet can be received by the module. This function should be called after switching on the module in the case the user wants to prepare the module for receive packets.
Besides, the getMultiPacket() function allows the user to wait for an incoming LAN packet. The period of time to wait is indicated as input in seconds units.
If a packet is received within the specified period of time, the function returns with ok response and the packet contents are stored in _packet structure. The incoming packet will always be a 17-byte length message (represented as a string), independently of the number of bytes sent. If the packet length is less than the maximum size, then the received message is always padded with “00” bytes. If no packet arrives within the given timeout, the function returns with error response.
In this receiving mode, the module continues in receive mode after calling the getMultiPacket() function. So, each time this function is called, a new packet arrival will be treated.
In addition, while the module is in receiving mode, the user is able to transmit packets. After the sending attempt, the module switches back to receiving mode again.
Example of use:
Related variable:
Sigfox._packet → Stores the received packet inside this string of 35 bytes
Example of receiving a packet as string:
The disableRX() function allows the user to disable the receiving mode. So the module stops listening to incoming packets.
Example of use:
It is possible to set up hybrid networks using both LAN and Sigfox protocols. Therefore, several nodes can use a LAN star topology to reach a central node which will access to the Sigfox network to route the information. This central node can be called the gateway of the network. The basis of this operation is that the gateway listens to LAN packets and sends them to the Sigfox infrastructure. See the following diagram to understand this hybrid network:
The user must keep in mind that there is a mismatch between the maximum payload in LAN networks (17 bytes) and Sigfox networks (12 bytes). So, the gateway node will need to select the useful 12 bytes from the LAN packet to be sent to the Sigfox network.
The following example shows how to operate as a gateway node sending the first 12 bytes of the incoming LAN packets to the Sigfox network:
Constant
Description
SIGFOX_ANSWER_OK
Successful response to a function
SIGFOX_ANSWER_ERROR
Erratic response to a function
SIGFOX_NO_ANSWER
No response to a command
AT_OK
Static string to check successful responses from the module
AT_ERROR
Static string to check erratic responses from the module
AT_HEADER
Static string to create commands
AT_HEADER_SLASH
Static string to create commands
Variable
Description
_buffer
The buffer of memory used for storing the responses from the module
_length
The useful length of the buffer
_def_delay
The time to wait after sending every command until listen for a response
_baudrate
The baudrate to be used when the module is switched on
_uart
The MCU uart selected (regarding the socket used: SOCKET0 or SOCKET1)
_command
The buffer of memory used for creating commands to be sent to the module
_txFreq
The carrier frequency for uplink communication
_rxFreq
The carrier frequency for downlink communication
_firmware
The buffer of memory where the module's firmware is stored
_id
The Sigfox module unique ID (given when it is registered)
