5.2.3. Sigfox driver Detailed Design Documentation

⚠️ This document is obsolete

5.2.3.1. General description

This specification specifies the functionality, API and the configuration of the Sigfox communication module driver. This driver is being developed for the AX-SFEU (and its Evaluation board) Sigfox module from ON Semiconductor.

Sigfox Chip : https://www.onsemi.com/PowerSolutions/product.do?id=AX-SFEU

AX-SFEU-1-01-TX30 datasheet : Local link AX-SFEU-D_Rev8.PDF , Onsemi website link

EU-SIGFOX-GEVB: IoT IDK EU Sigfox Evaluation Board : Link

Back to top

5.2.3.2. Acronyms and abbreviations

drv, DRV : driver

HAL : Hardware Abstraction Layer

OoB : Out-of-Band

enum : C enumeration

struct : C structure

dl : Downlink, a frame sent by a station to a device

App : User-written Application

Back to top

5.2.3.3. Constraints and assumptions

5.2.3.3.1. Limitations

The supported functionalities are :

  • Sending a frame

  • Sending a frame and asking a downlink frame

  • Sending a bit

  • Sending a bit and asking a downlink frame

  • Sending an OOB message

  • Retrieving the unique ID of the chip

  • Retrieving the PAC of the chip

  • Retrieving the chip's Sigfox Library Software version

The following functionalities of the chip are not supported as they are not strictly required for an end user.

  • Get and set the transmit repeat value

  • Get and set the value of the SF-EU registers

  • Get the range of the SF-EU registers

  • Get and set the RX frequency

  • Get and set the TX frequency

  • Run continuous wave mode

  • Run TX constant byte mode

  • Get the chip's temperature

  • Get the chip's voltage

  • Get the following information : Software Name & Version, Contact Details, Silicon revision lower byte, Silicon revision upper byte, Major Firmware Version, Minor Firmware Version, Firmware Variant, Firmware VCS Version

  • Set the power mode

  • Use the chip's GPIO in any way

  • Use the SPI interface of the chip available with AT commands

  • Use the Sigfox test mode

  • Send & Receive PN9 bitstream for BER measurements

  • Send and receive local loop

Some functionalities such as setting the RX/TX frequencies, accessing the chip's configuration registers or managing the chip's power modes may be supported in future versions.

5.2.3.3.2. Assumptions

This driver is being developed under the following assumptions :

  • Resistors R24, R25 and R74 are removed from the EU-SIGFOX-GEVB: IoT IDK EU Sigfox Evaluation Board, as they force the use of a I2C driver to control the PCA9655E on the evaluation board. Developing an I2C driver for this component is out of the scope of this driver.

  • The commands are sent via a serial line UART interface. The use of the serial line is out of scope of this driver and is used through the HAL.

Back to top

5.2.3.4. Dependencies

5.2.3.4.1. OSS

mpOSS_EXE__CHEST : This macro returns the pointer to the current process' chest

mEGOS_EXE__THIS_DECL : This macro is used to transmit This pointer inside functions

mOSS_EXE__CURRENT : This macro returns the current task/process' handle

mOSS_EXE__PROC : This macro defines a new process

mOSS_EXE__STARTED : This macro returns the current process' reason of start

mOSS_MSG__RECEIVE : This macro starts the message loop (hides a switch/case)

mOSS_MSG__ID : This macro returns the unique value associated to a message and a message type

mOSS_MSG__EXIT : This macro exits from message loop (acts like a break from the switch/case)

mOSS_MSG__LOOP : This macro ends the message loop (closes the switch/case)

5.2.3.4.2. HAL

uErr_Code (hal_com_Transmit)(sHalCom_ApiTransmit api)

uErr_Code (hal_com_Transfer)(sHalCom_ApiTransfer api)

uErr_Code (hal_com_Open)(sHalCom_ApiId i_sId)

uErr_Code (hal_com_Close)(sHalCom_ApiId i_sId)

uErr_Code (hal_com_Enable)(sHalCom_ApiEnable i_sEnable)

uErr_Code (hal_com_Disable)(sHalCom_ApiId i_sId)

5.2.3.4.3. UTL

utl_num_str_to_Hexa

Back to top

5.2.3.5. File Structure

5.2.3.5.1. Public files

The SRC/inc/egos_drv/egos_drv_com_lpwan.h file defines which files to include according to configuration and which APIs are available, and defines common structures and constants for the different LPWAN

The SRC/inc/egos_drv/egos_drv_com_lpwan__cfg.h file is a configuration file used to signal the OS and the user which LPWAN module is available on the product

The SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h file defines every structures and enumerations available for the user. It contains the messages the drivers can send, the API signals, the API configuration, the API functions, the API's Send structure and the name of the Sigfox process.

The SRC/inc/egos_err__code.h file contains the error codes sent by the driver.

5.2.3.5.2. Private files

The SRC/src/egos_drv/drv_com_lpwan.h file is a header inclusion file needed for the LPWAN process and contains function prototypes, constants, structures, etc common to the different LPWAN

The SRC/src/egos_drv/drv_com_lpwan_.c file contains the reference to the Sigfox API functions

The SRC/src/egos_drv/drv_com_lpwan_sigfox.h file lists all the possible Sigfox chip implementation through their header files and contains function prototypes, constants, structures, etc common to the different Sigfox implementations

The SRC/src/egos_drv/drv_com_lpwan_sigfox_.c file is used to select the right Sigfox chip implementation and contain chip independent Sigfox code

The SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu.h file defines the states of the driver, the error codes of the driver and the driver's API prototypes.

The SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu_.c file is the main file for the implementation, it contains the definition of the chest of the Sigfox process, the local function of the driver (like opening and closing the communication channel to the chip), the definition of the driver's process, the definition of the API's functions.

The SRC/src/egos_drv/drv_com_lpwan_sigfox_impl_ax_sfeu__map.cxx file abstracts the list of the AT commands to be sent to the Sigfox module

The SRC/src/egos_drv/drv_com_lpwan_sigfox_impl_ax_sfeu__reg.h file abstracts the list of registers of the Sigfox module

Back to top

5.2.3.6. Functional specification

5.2.3.6.1. Driver Scope

The purpose of this driver is to abstract the use and functionalities of the AX-SFEU chip to a user writing an App. This driver should provide all the basic functionalities needed to operate in a Sigfox network. It does not let the user access the other functionalities of the AX-SFEU chip, like GPIO for example. This driver does not allow more than one process to be its master.

5.2.3.6.2. Driver State Machine

The Sigfox driver has the following state machine, which consists in 5 states :

  • Uninitialized (eDRV_COM_LPWAN_SIGFOX__STATE__UNINITIALIZED) : The driver is in an Uninitialized state, meaning it is not initialized and must be initialized before use. In this state it will only try to initialize the chip and itself, it won't treat any messages. In this state the only API commands it will accept is the Control command and the Release command. Any other command will send a eDRV_COM_LPWAN_SIGFOX__MSG__ERROR message with the cDRV_COM_LPWAN_SIGFOX__ERR__DRV_BUSY error code. If the chip times out during initialization, the drivers goes to the eDRV_COM_LPWAN_SIGFOX__STATE__TIMEOUT state. It can transition to

    • the Standby state

    • the Timeout state with a Timeout event

  • Standby (eDRV_COM_LPWAN_SIGFOX__STATE__STANDBY) : The driver is in a Standby State, meaning it is awaiting commands. If it has stored commands, it will send them. It can transition to

    • the Sleep state with a Sleep message

    • the WaitingResponse state when a Command is stored

  • Sleep (eDRV_COM_LPWAN_SIGFOX__STATE__SLEEP) : The device is in a Sleep state, meaning the device is in a Low Power state and will not respond to commands, but will still send periodically OoB messages. Any commands sent in this state will be stored by the driver, and the driver will wake up the module. It can transition to

    • the Standby state with a Wakeup message
  • WaitingCommandResponse (eDRV_COM_LPWAN_SIGFOX__STATE__WAITINGRESPONSE) : The driver is in a WaitingCommandResponse state, meaning it is waiting a response from the module for the last sent command. If the answer is received, it is processed and the driver switch to the Standby state. Any commands sent to the driver in this state will be stored and treated the next time the driver is in the Standby state. In this state, the process counts the passing time and can trigger a Timeout state. It can transition to

    • the Timeout state with a Timeout event

    • the Standby state with a answer message

  • Timeout (eDRV_COM_LPWAN_SIGFOX__STATE__TIMEOUT) : The driver is in a Timeout state, meaning the chip has not responded in the appropriated time. The driver tries to re enable communication with the chip : it resets the chip and sends the dummy command. When the chip has answered, the driver will try a initialization phase. It can transition to

    • the Uninitialized state with a eDRV_COM_LPWAN_SIGFOX__REG__ANS_OK message

SigFox_Driver_State_Machine_diagram

5.2.3.6.3. Initialization

The initialization phase is pretty simple : the driver opens a communication channel with the AX-SFEU (in most case a 9600 8N1 UART communication bus, but it is the role of the HAL to determine this), asks the AX-SFEU its ID, PAC and Library Version and stores it in the chest of the Sigfox process (see 7.1.14 sDrvComLpwanSigfox_Chest) as a sDrvComLpwanSigfox_ApiChipInfo struct (see 7.1.5 sDrvComLpwanSigfox_ApiChipInfo). If need be, future versions the driver might also set the sending and receiving frequencies of the AX-SFEU.

Here are the steps taken by the process for the driver for initialization (see also 8.1 Initialization and 8.11 Boot sequence ) :

  • Step 1 : Opens a HAL communication channel

  • Step 2 : Asks the device ID

  • Step 3 : Asks the device PAC

  • Step 4 : Ask the device Library Version

  • Step 5 : Go to Standby State

If any of these steps times out, the HAL communication channel is closed, the chip is reset and initialization is retried.

5.2.3.6.4. Tx

Thanks to the HAL and the mapper, the AX-SFEU is seen as an internal module of the microprocessor with its own registers, and all communication to the AX-SFEU are simply done by writing the data and commands to the corresponding registers.

Data is sent thanks to the Mapper with the mpDRV_COM_LPWAN_SIGFOX__MAP__CMD() macro with the SF or SB parameters.

Only the master controller of the driver can send data to the Sigfox network. Any process can ask for the ID, the PAC and the Library version. The AX-SFEU is simple enough to be able to handle multiple master at the same time, but doing so we cannot guarantee a maximum response time. Having only one master also make this driver similar to other communication drivers.

If the App wants to send multiple frames in a short period of time, the driver stores them and sends them one at the time (see 8.10 Multiple Send through API)

It is the App responsibility to make sure the answer from the driver arrives to the right process. For example, if the series of event described in diagram 8.6 Erroneous Send Sequence occurs, the response from the driver will be sent to Task r2 instead of Task r1. The user shall wait that all of his messages are processed before releasing control of the driver.

This behavior is due to the fact that a App can send multiple frames in a short period of time and the driver stores it so the App does not have to wait every time it want to transmit data.

5.2.3.6.5. Rx

The AX-SFEU only receives data when a downlink is asked as defined in the Sigfox protocol. Receiving a downlink frame can take up to 45/50 seconds. This long delay is defined by protocol : after the AX-SFEU has sent the first of the three sends, it starts a 20 second timer. After this 20 second period, it waits up to 25 seconds in listening mode for the downlink frame. If no frames are received during this period, an error message is sent to the user, and if the downlink frame is received, it is transmitted as is to the user.

This long waiting period forces the use of a complete asynchronous communication between the App and the driver : when asking for a downlink, the API are never blocking. When the driver has the chip's response, it sends it with either the eDRV_COM_LPWAN_SIGFOX__MSG__RECEIVE message if a downlink has been received or with the cDRV_COM_LPWAN_SIGFOX__ERR__DL_TIMEOUT error code in a eDRV_COM_LPWAN_SIGFOX__MSG__ERROR message if no downlink frame has been received.

Receiving a downlink frame is done with the mpDRV_COM_LPWAN_SIGFOX__MAP__CMD() macro, with the downlink field of the command set to 1. Once the command has been sent, the mapper should send a eDRV_COM_LPWAN_SIGFOX__REG__ANS_OK message once the answer has been received. This is an asynchronous message and should be received in a message loop

Every command sent to the chip will trigger an answer from the chip, but the timing between the command and the answer is different for each commands.

Here are the following delays between the end of a command and the end of the answer from the chip :

Command Description Delay (ms)
AT Corresponds to the CHECKALIVE message, it is a dummy command used to check if the chip is responding ~ 4.4
AT$SB=1 Sends a bit to the network without a downlink ~ 5 950
AT$SF='max frame size ie. 12 bytes' Sends a frame to the network without a downlink ~ 8 830
AT$SF='data',1 Sends a frame to the network and wait for a downlink ~ 50 000
AT$SB='bit',1 Sends a bit to the network and wait for a downlink ~ 50 000
AT$SO Sends a Out Of Band message ~ 7.9
AT$I=9 Retrieve the Sigfox Software Library Version ~ 13
AT$I=10 Retrieve the chip ID ~ 11.4
AT$I=11 Retrieve the chip PAC ~ 19.6
Command Constant Value (s)
AT cDRV_COM_LPWAN_SIGFOX__TIMEOUT_CHECKALIVE_BASE 50000ULL
SB='data',0 ; SF='data',0 cDRV_COM_LPWAN_SIGFOX__TIMEOUT_DATA_BASE 8900000ULL
SB='data',1 ; SF='data',1 cDRV_COM_LPWAN_SIGFOX__TIMEOUT_DOWNLINK_BASE 50000000ULL
SO cDRV_COM_LPWAN_SIGFOX__TIMEOUT_OOB_BASE 7900000ULL
I=9 cDRV_COM_LPWAN_SIGFOX__TIMEOUT_SFLIB_BASE 56000ULL
I=10 cDRV_COM_LPWAN_SIGFOX__TIMEOUT_ID_BASE 50000ULL
I=11 cDRV_COM_LPWAN_SIGFOX__TIMEOUT_PAC_BASE 80000ULL

Some of the values are very different from the measured values, because we can not predict how many other processes run in the OS, so we can not be very precise with those timeout delays.

The time the driver will wait for an answer is computed as follow : 1.2 * Constant . The timeout values correspond to 120% of the measured value because the datasheet of the AX-SFEU does not guarantee responses times so some precautions must be taken. The 20% value is taken arbitrarily and can be changed if needed by modifying the cDRV_COM_LPWAN_SIGFOX__TO_MULT constant.

Back to top

5.2.3.7. API Specification

5.2.3.7.1. Types definition

5.2.3.7.1.1. eDrvComLpwanSigfox_Msg

eDrvComLpwanSigfox_Msg , enum of the different messages that the driver can send. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field Description
eDRV_COM_LPWAN_SIGFOX__MSG__NONE No message
eDRV_COM_LPWAN_SIGFOX__MSG__CONTROL_CONF Confirmation that the driver has accepted control from the calling process
eDRV_COM_LPWAN_SIGFOX__MSG__CONTROL_DENIED Message indicating that the driver has refused control from the calling process
eDRV_COM_LPWAN_SIGFOX__MSG__RELEASE_CONF Confirmation that the calling process has now released control over the Sigfox driver
eDRV_COM_LPWAN_SIGFOX__MSG__RECEIVE Message indication that the Sigfox driver has receive a Sigfox downlink frame
eDRV_COM_LPWAN_SIGFOX__MSG__SEND_CONF Confirmation that the message has been sent
eDRV_COM_LPWAN_SIGFOX__MSG__ERROR Message indicating that the message could not be sent, must be sent with a error code
eDRV_COM_LPWAN_SIGFOX__MSG__ID Message returning the Sigfox ID
eDRV_COM_LPWAN_SIGFOX__MSG__PAC Message returning the Sigfox PAC
eDRV_COM_LPWAN_SIGFOX__MSG__SFLIBVER Message returning the chip's Sigfox Library Version

5.2.3.7.1.2. eDrvComLpwanSigfox_Command

eDrvComLpwanSigfox_Command , enum of the different commands the driver can send tot the device and that receive an asynchronous answer. It allows the driver to know what each communication from the device means. Must be located in SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu.h

Field Description
eDRV_COM_LPWAN_SIGFOX__COMMAND_SENDFRAME The last command was sending a frame
eDRV_COM_LPWAN_SIGFOX__COMMAND_SENDBIT The last command was sending a bit
eDRV_COM_LPWAN_SIGFOX__COMMAND_SLEEP The last command was setting the device to sleep
eDRV_COM_LPWAN_SIGFOX__COMMAND_WAKEUP The last command was waking up the device
eDRV_COM_LPWAN_SIGFOX__COMMAND_CHECKALIVE The last command was checking if the device was still responding
eDRV_COM_LPWAN_SIGFOX__COMMAND_RESET The last command was resetting the device
eDRV_COM_LPWAN_SIGFOX__COMMAND_OOB The last command was sending an OoB message

5.2.3.7.1.3. eDrvComLpwanSigfox_Api

eDrvComLpwanSigfox_Api, enum of the different messages the App can send to the driver. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field Description
eDRV_COM_LPWAN_SIGFOX__API_MSG__NONE No message
eDRV_COM_LPWAN_SIGFOX__API_MSG__CONTROL_REQ Requires the control of the Sigfox module
eDRV_COM_LPWAN_SIGFOX__API_MSG__RELEASE Releases the control of the drive
eDRV_COM_LPWAN_SIGFOX__API_MSG__SENDFRAME Send a 1-12 bytes Sigfox Frame
eDRV_COM_LPWAN_SIGFOX__API_MSG__SENDBIT Send a bit to the Sigfox network
eDRV_COM_LPWAN_SIGFOX__API_MSG__SEND_OOB Send an Out of Band (OoB) message to the network
eDRV_COM_LPWAN_SIGFOX__API_MSG__GET_ID Get the device's unique ID
eDRV_COM_LPWAN_SIGFOX__API_MSG__GET_PAC Get the device's PAC
eDRV_COM_LPWAN_SIGFOX__API_MSG__GET_SFLIBVER Get the chip's Sigfox Library Version

5.2.3.7.1.4. sDrvComLpwanSigfox_SigfoxLibVer

sDrvComLpwanSigfox_SigfoxLibVer, struct of the different configurations needed to setup the module. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field name Type Description
anLibVer[20] nU8 Version of the Sigfox Library used by the chip
nSize nU8 Size of libVer

The size of the array is set to 20 for the following reasons :

  • The AX-SFEU answer with a 10 bytes long string, but as this is not documented in the chip datasheets, by precaution the array is twice a large.

5.2.3.7.1.5. sDrvComLpwanSigfox_ApiChipInfo

sDrvComLpwanSigfox_ApiChipInfo, struct of the different information about the module. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field name Type Description
nId nU32 Unique ID of the chip
nPac nU64 PAC of the device
sSfLibVer sDrvComLpwanSigfox_SigfoxLibVer Version of the Sigfox Library used by the chip

Only those three fields are stored, as they are the only common fields on the AX-SFEU and the OL2385SWUG.

This data is stored into the chest of the process but could have been asked to the chip every time the App would have needed it. It was designed this way because communicating to the device is slow (and probably more energy consuming). If there is a major RAM usage issue, this could be removed but then a massive delay (up to 50 seconds if a single downlink was previously asked, more if other commands are waiting) can happen between the query and the answer.

5.2.3.7.1.6. sDrvComLpwanSigfox_Api

sDrvComLpwanSigfox_Api, struct containing the different functions of the API, corresponding to the eDrvComLpwanSigfox_Api messages. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field name Type Description
Ver nU32 Version of the API
uErr_Code (*Control)(void) Function pointer Takes control of the driver if the driver does not already have a master, does nothing if driver has already a master
uErr_Code (*Release)(void) Function pointer Releases control of the driver, does nothing if not in control
uErr_Code (*SendFrame)(psDrvComLpwanSigfox_ApiSend i_psSend) Function pointer Sends the frame in the i_sSend structure
uErr_Code (*SendBit)(psDrvComLpwanSigfox_ApiSend i_psSend) Function pointer Sends a single bit
uErr_Code (*SendOob)(void) Function pointer Sends an Out-of-Band message to the Network
uErr_Code (*GetId)(void) Function pointer Gets the device's unique ID
uErr_Code (*GetPac)(void) Function pointer Gets the device's PAC
uErr_Code (*GetSFLibraryVersion)(void) Function pointer Gets the device's Sigfox Library Version

5.2.3.7.1.7. sDrvComLpwanSigfox_ApiFrame

sDrvComLpwanSigfox_ApiFrame, struct containing a frame and its size. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field name Type Description
anBuff[12] nU8 Data buffer, cannot exceed 12 bytes long
nSize nU8 Size of the data buffer, 12 bytes maximum

5.2.3.7.1.8. uDrvComLpwanSigfox_ApiUnionSend

uDrvComLpwanSigfox_ApiUnionSend, union containing the two Sigfox send option : frame and bit. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field name Type Description
sFrame sDrvComLpwanSigfox_ApiFrame Sigfox frame
bBit bB1 Sigfox bit

5.2.3.7.1.9. sDrvComLpwanSigfox_ApiSend

sDrvComLpwanSigfox_ApiSend, struct containing the different fields sent to the Sigfox network. Must be located in SRC/inc/egos_drv/egos_drv_com_lpwan_sigfox.h

Field name Type Description
uBuff uDrvComLpwanSigfox_ApiUnionSend Data to be sent
bDownlink bB1 Is a downlink required, 0 for no, yes for 1, 4 downlinks per day maximum

5.2.3.7.1.10. eDrvComLpwanSigfox_State

eDrvComLpwanSigfox_State, enum of the different states of the driver. Must be located in SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu.h

See chapter 6.2

Field Description
eDRV_COM_LPWAN_SIGFOX__STATE__NONE The driver is in an unknown state, generally after boot
eDRV_COM_LPWAN_SIGFOX__STATE__UNINITIALIZED The driver is uninitialized state, meaning it must be initialized before use
eDRV_COM_LPWAN_SIGFOX__STATE__STANDBY The drivers awaits the next command
eDRV_COM_LPWAN_SIGFOX__STATE__SLEEP The SF module is in a Sleeping state and must be woken up before another command is sent
eDRV_COM_LPWAN_SIGFOX__STATE__WAITINGRESPONSE The driver has sent a non sleep command to the SF module and await its response
eDRV_COM_LPWAN_SIGFOX__STATE__TIMEOUT The chip is failing to answer and the driver is trying to communicate with it

5.2.3.7.1.11. Error codes

The following constants correspond to the different error codes the driver can sent to the App. Must be located in SRC\inc\egos_err__code.h

Field Description Definition
cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__DATA_SIZE Data is not of an expected size mERR__CODE(eERR__SRC__DRIVER, eERR__TYP__BUFFER, eERR__SUF__SUPERIOR, eERR__DEV__SIGFOX, eERR__EQU__ERROR)
cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__DRV_BUSY The driver is busy, the user must wait. mERR__CODE(eERR__SRC__DRIVER, eERR__TYP__WRITE, eERR__SUF__ACCEPTED, eERR__DEV__SIGFOX, eERR__EQU__NOT)
cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__NO_CONTROL The App does not have the control of the driver mERR__CODE(eERR__SRC__DRIVER, eERR__TYP__ACCESS, eERR__SUF__ACCEPTED, eERR__DEV__SIGFOX, eERR__EQU__NOT)
cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__DL_TIMEOUT The driver has not received the downlink mERR__CODE(eERR__SRC__DRIVER, eERR__TYP__READ, eERR__SUF__TIMEOUT, eERR__DEV__SIGFOX, eERR__EQU__ERROR)
cERR__CODE__NO_PROCESS The Sigfox process has not been found mERR__CODE(eERR__SRC__THREAD, eERR__TYP__HANDLE, eERR__SUF__EXIST, eERR__DEV__UNKNOWN, eERR__EQU__NOT)
cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__NETWORK_ERR There has been a problem with the Sigfox, the data has not been sent mERR__CODE(eERR__SRC__DRIVER, eERR__TYP__CONNECT, eERR__SUF__FAILED, eERR__DEV__SIGFOX, eERR__EQU__ERROR)

5.2.3.7.1.12. sDrvComLpwanSigfox_MessageList

sDrvComLpwanSigfox_CommandList, struct representing all the commands waiting to be sent. Must be located in SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu.h

Field name Type Description
sSend sDrvComLpwanSigfox_ApiSend Data to be sent
psNextMsg psDrvComLpwanSigfox_MessageList Pointer to the next data
eType eDrvComLpwanSigfox_Api Type of the command, corresponding to the eDRV_COM_LPWAN_SIGFOX__API_MSG it was sent with

5.2.3.7.1.13. sDrvComLpwanSigfox_SentCommandInfo

sDrvComLpwanSigfox_SentCommandInfo, struct used to memorize which type of answer is awaited. Must be located in SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu.h

Field name Type Description
eType eDrvComLpwanSigfox_Command Type of the command sent
bDownlink bB1 Is a downlink awaited (Used only for eDRV_COM_LPWAN_SIGFOX__COMMAND_SENDFRAME and eDRV_COM_LPWAN_SIGFOX__COMMAND_SENDBIT)

5.2.3.7.1.14. sDrvComLpwanSigfox_Chest

sDrvComLpwanSigfox_Chest, struct of the chest of the main Sigfox process. Must be located in SRC/src/egos_drv/drv_com_lpwan_sigfox__impl_ax_sfeu.h

Field name Type Description
nSwVer nU32 Number of the current version of the driver
sChipInfo sDrvComLpwanSigfox_ApiChipInfo Structure containing information about the module and its configuration
eState eDrvComLpwanSigfox_State State of the driver
psCommandList psDrvComLpwanSigfox_CommandList List of the waiting commands
sSentCommandInfo sDrvComLpwanSigfox_SentCommandInfo Information on the last sent command, used to check the answer
hMasterHandle hHandle Handle of the process that has the control of the driver
nTimeoutStart nU64 Clock tick of the start of the timeout countdown
nTimeoutThreshold nU64 Timeout threshold
anRxBuff[cDRV_COM_LPWAN_SIGFOX__CFG__RX_BUFFER_LENGTH] nU8 Receive buffer for the HAL
nRxCount nU32 Size of the receive buffer
anReg[sizeof(uDrvComLpwanSigfox_Reg)] nU8 Registers for the mapper
anFrame[cDRV_COM_LPWAN_SIGFOX__CFG__FRAME_LENGTH] nU8 Frame storing the data received from the mapper
eReg eDrvComLpwanSigfox_Reg Last accessed register or answer
eRst eHalCom_Id Reset
sMap sHalMap Mapper for the SF AX-SFEU chip

Back to top

5.2.3.7.2. Function definitions

Function egos_drv_com_lpwan_sigfox_Control
Prototype uErr_Code egos_drv_com_lpwan_sigfox_Control(void)
Description This function tries to take the driver's control. Does nothing if the process already has control or if control is not possible
Parameters No parameters
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__CONTROL_REQ
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__CONTROL_CONF is control acquired , eDRV_COM_LPWAN_SIGFOX__MSG__CONTROL_DENIED if control denied
Function egos_drv_com_lpwan_sigfox_Release
Prototype uErr_Code egos_drv_com_lpwan_sigfox_Release(void)
Description This function releases control over the driver. Does nothing if the process did not have the control
Parameters No parameters
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__RELEASE
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__RELEASE_CONF, eDRV_COM_LPWAN_SIGFOX__MSG__ERROR (possible errors : cDRV_COM_LPWAN_SIGFOX__ERR__NO_CONTROL)
Function egos_drv_com_lpwan_sigfox_SendFrame
Prototype uErr_Code egos_drv_com_lpwan_sigfox_SendFrame(sDrvComLpwanSigfox_ApiSend i_sSend)
Description This function sends a frame via the Sigfox Network
Parameters sDrvComLpwanSigfox_ApiSend i_sSend : IN Structure containing the data to be sent
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__SENDFRAME
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__SEND_CONF if transmission successful , eDRV_COM_LPWAN_SIGFOX__MSG__RECEIVE if downlink frame received, eDRV_COM_LPWAN_SIGFOX__MSG__ERROR (possible errors : cDRV_COM_LPWAN_SIGFOX__ERR__DL_TIMEOUT, cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__DATA_SIZE, cDRV_COM_LPWAN_SIGFOX__ERR__NO_CONTROL) if an error has occurred
Function egos_drv_com_lpwan_sigfox_SendBit
Prototype uErr_Code egos_drv_com_lpwan_sigfox_SendBit(sDrvComLpwanSigfox_ApiSend i_sSend)
Description This function sends a single bit via the Sigfox Network
Parameters sDrvComLpwanSigfox_ApiSend i_sSend : IN Structure containing the data to be sent
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__SENDBIT
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__SEND_CONF if transmission successful, eDRV_COM_LPWAN_SIGFOX__MSG__RECEIVE if downlink frame received, eDRV_COM_LPWAN_SIGFOX__MSG__ERROR (possible errors : cDRV_COM_LPWAN_SIGFOX__ERR__DL_TIMEOUT, cERR__CODE__DRV_COM_LPWAN_SIGFOX__ERR__DATA_SIZE, cDRV_COM_LPWAN_SIGFOX__ERR__NO_CONTROL) if an error has occurred
Function egos_drv_com_lpwan_sigfox_SendOob
Prototype uErr_Code egos_drv_com_lpwan_sigfox_SendOob(void)
Description This function sends an OoB message to the Sigfox network
Parameters No parameters
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__SEND_OOB
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__SEND_CONF if transmission successful, eDRV_COM_LPWAN_SIGFOX__MSG__ERROR (possible errors : cDRV_COM_LPWAN_SIGFOX__ERR__NO_CONTROL) if an error has occurred
Function egos_drv_com_lpwan_sigfox_GetId
Prototype uErr_Code egos_drv_com_lpwan_sigfox_GetId(void)
Description This function asks for the unique ID of the Sigfox device
Parameters None
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__GET_ID
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__ID with the ID as data. The data is a nU32
Function egos_drv_com_lpwan_sigfox_GetPac
Prototype uErr_Code egos_drv_com_lpwan_sigfox_GetPac(void)
Description This function asks for the device's PAC
Parameters None
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__GET_PAC
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__PAC with the PAC as data. The data is a nU64
Function egos_drv_com_lpwan_sigfox_GetSFLibraryVersion
Prototype uErr_Code egos_drv_com_lpwan_sigfox_GetSFLibraryVersion(void)
Description This function asks for the chip's Sigfox library version
Parameters None
Return value cERR__CODE__NO_PROCESS if the Sigfox process has not been found, cERR__CODE__OK if the message has been sent, and all of the error codes of mOSS_MSG__SEND
Messages sent eDRV_COM_LPWAN_SIGFOX__API_MSG__GET_SFLIBVER
Messages received eDRV_COM_LPWAN_SIGFOX__MSG__SFLIBVER with the Sigfox library version as data. The data is a String
Function drv_com_lpwan_sigfox__impl_ax_sfeu_Close
Prototype __STATIC uErr_Code drv_com_lpwan_sigfox__impl_ax_sfeu_Close(mEGOS_EXE__THIS_DECL())
Description This function closes the HAL connexion between the driver and the chip
Parameters mEGOS_EXE__THIS_DECL() : IN/OUT passes the This pointer
Return value cERR__CODE__OK if communication xas close successfully, and all of the error codes of hal_com_Close and hal_com_Disable
Messages sent None
Messages received None
Function drv_com_lpwan_sigfox__impl_ax_sfeu_Open
Prototype __STATIC uErr_Code drv_com_lpwan_sigfox__impl_ax_sfeu_Open(mEGOS_EXE__THIS_DECL())
Description This function opens the HAL connexion between the driver and the chip
Parameters mEGOS_EXE__THIS_DECL() : IN/OUT passes the This pointer
Return value cERR__CODE__OK if communication has been opened sucessfully, and all of hal_com_Open and hal_com_Enable error codes
Messages sent None
Messages received None
Function drv_com_lpwan_sigfox_AddCommandList
Prototype __STATIC void drv_com_lpwan_sigfox_AddCommandList(psDrvComLpwanSigfox_CommandList i_psCommandToAdd, psDrvComLpwanSigfox_CommandList io_psCommandList)
Description This function adds a command to the end of command list
Parameters psDrvComLpwanSigfox_CommandList i_psCommandToAdd : IN the command to add, psDrvComLpwanSigfox_CommandList io_psCommandList IN/OUT the list of commands
Return value None
Messages sent None
Messages received None

5.2.3.7.3. Call-back notifications

This driver has not callback, everything is done through the mapper.

5.2.3.7.4. Scheduled functions

The only scheduled function of the driver is its main process (drv_com_lpwan_sigfox__impl_ax_sfeu_Main).

Back to top

5.2.3.8. Sequence diagrams

5.2.3.8.1. Initialization

5.2.3.8.2. Sending a frame through API

5.2.3.8.3. Control required through API

5.2.3.8.4. Release through API

5.2.3.8.5. Sending a bit through API

5.2.3.8.6. Erroneous Send Sequence

5.2.3.8.7. Send OoB through API

5.2.3.8.8. Get ID through API

5.2.3.8.9. Get PAC through API

5.2.3.8.10. Multiple Send through API

5.2.3.8.11. Boot sequence

5.2.3.8.16. Send frame with API but network error occurred