- Introduction
- Getting Started
- Connecting your EDK
- Test programs
- Low-power Operation
- Headers and Functions
- Analog Input
- One-Wire Temperature Sensor (DS18B20)
- Emulated EEPROM Memory
- Events
- 6-Axis Sensor with Linear Accelerometer and Magnetometer (FXOS8700CQ)1
- General-Purpose Input/Output (GPIO)
- Real-Time Clock (RTC)
- Ambient Light Sensor (SI1133)
- Temperature & Humidity Sensor (SI7021)
- SIGFOX Modem / Radio
- USB and Debugging
- Thermocouple Input (MCP9600)1
- Useful Links
1 Optional sensors. Check availability before purchasing.
This is a repository for examples and source code (excluding source code for our library and sensitive information) regarding the uDEV Embedded Development Kit (EDK), a multi-sensor board designed for developers and users who wish to create quick and complete solutions without the need for additional sensors.
The EDK is distributed through the SIGFOX Partners network, and available to purchase directly from us.
A 3D model of the uDEV EDK
To contact us directly, please send an e-mail to contato@udev.com.br.
We have made available files that can be used to test your board, or as templates for bigger projects.
These examples can be used to read the value of each sensor on the board, and from there you can develop your own program and start using your EDK.
We recommend having the following software to work on your EDK:
- Atmel Studio 7.0
- Microchip's SAM Bootloader Assistant (SAM-BA) 2.17
- A terminal software of your choice Check our useful links section to find where to obtain these.
Before you start developing with Atmel Studio, be sure to check our Manual on how to install the processor files, so your project compiles correctly.
By default, Atmel Studio doesn't install the files for every and each processor, so your application will say you don't have the "samd21.h" file included.
After installing the SAM D21 processor family with the device pack manager on Atmel, this problem is solved. More details on our manual.
When writing your application, you also have to pay attention to its memory addressing.
Your program MUST be built with its Flash Memory address starting at 0x6000. Lower addresses are reserved for our Bootloader.
To write any program on the board via USB, you may use SAM-BA (version 2.16 or 2.17 are guaranteed to work).
Refer to our full manual for a guide for installing and using your EDK with SAM-BA.
You will need our static library to build your code. The latest release available can be found in the Library folder in this repository.
Instructions on how to change your program's memory address, install and use SAM-BA are in our full manual, available in this repository.
Note that addressing instructions are available only for Atmel Studio 7.0.
In this manual you will also find information on each sensor, along with their datasheets and full specifications.
To connect your EDK to your computer via USB, simply plug in the Micro USB cable. From there on, you can use SAM-BA to upload to the board the binary file of any application you wish.
The board should turn on with a solid blue light, indicating it is on Bootloader Mode.
It can enter this state with an application already uploaded, by keeping the button pressed while powering up the board.
When using an on-chip programmer, such as the ATMEL-ICE, you may write your program directly from Atmel Studio 7.0 or similar.
When using a programmer to write directly to the chip, remember to write your program starting at the address 0x6000 or higher, or you'll risk writing over the bootloader!
In this repository you'll find many example files, to run and test your EDK board.
Use the static library we generated from our board configuration files to run your tests.
The latest version of the library can be found in the Library folder in this repository.
We have created a generic template for Atmel Studio 7.0, so that you can quickly create projects for the uDEV Sigfox EDK, without needing to choose the type of processor and set all the parameters every time.
The process of installing templates in Atmel Studio is described at length in our full manual, please refer to it as a step-by-step guide if needed.
We will make available a zipped folder that includes all of our headers needed to compile and execute applicatons.
You'll need to extract the contents of said .ZIP to the /sdk/ directory that will be created within your project, and then add the Library to Atmel Studio. Use our manual on a step-by-step guide for how to add libraries to a project.
Also available is a LED Example Template, which you can use to quickly operate the LED in your board, testing it without having to add any other headers to the project, aside from the static library.
Apart from the static library, the files in the Example folder in this repository contain all you will need to run the program immediately, provided your EDK is connected in Bootloader Mode. Simply download the folder of which example you want to install, add the static library to the correct path, and open the .cproj file. Atmel Studio will generate a new solution for your example, and you will be able to run it.
Feel free to modify the program as you desire, to fit your testing needs.
This board is designed to operate in situations that require low-power, such as IoT applications without easy access to replace batteries.
In order to use USB Debugging, the board cannot be in low-power mode. USB connection requires a minimum of constant power, and that isn't supplied in low-power mode.
Low-power mode is the default, and as such, will not permit the use of USB serial communications with a terminal or alike.
Operation mode is dictated by a boolean variable that can be present at the start of your program. If this variable isn't declared, the program will start in low-power mode.
The code below will start the system in low-power, same as the default case.
bool __b_system_low_power_enabled_ = true;To use the USB serial communication, the variable must be false:
bool __b_system_low_power_enabled__ = false;Either way, the variable definition must be global, before the user setup and loop functions.
For some components, we opted to provide two methods of measurement.
We named these methods the Callback Mode and the Blocking Mode.
- The way we recommend doing it is using the Callback Mode, which allow the program to keep running uninterrupted, and have the callback function called automatically after the measurement is complete.
- The other method we provided is the Blocking Mode: After starting a new measurement, the entire program execution is halted until said measurement is complete.
This header contains functions for measuring analog input and battery voltage.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnINPUT_ANALOGIC_Init() | Initializes the analog input component. | None | None |
| fnINPUT_ANALOGIC_Read_Value (en_input_analogic_definition_t en_input, uint16_t * p_adc_raw, uint16_t * p_adc_mv) |
Returns the value measured in the analog input or the battery voltage. | en_input: Defines what to measure. INPUT_ANALOGIC_DEFINITION_VBAT for battery voltage; INPUT_ANALOGIC_DEFINITION_4_20_MA for analog input voltage; p_adc_raw: A pointer to the value that contains the raw value converted by the analog-digital converter (ADC); p_adc_mv: A pointer to the value that has the value converted by the ADC, in volts (V); |
None1 |
1This function returns the values via pointers. Define two uint16_t variables, and assign their addresses to the function parameters. These variables' values will contain the results.
Use this header to implement temperature readings using one or more DS18B20 sensors, with the 1-wire thermometers connected to the analog input connectors.
If more than one probe will be used, please be wary of the process of identifying and initializing them correctly.
To properly use the analog input with the DS18B20 Temperature Sensor, the EDK has to be slightly modified.
Please refer to the Board Modifications folder to see which components need to be present in each configuration.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnDS18B20_Init(uint8_t u8_devices) | Initializes the DS18B20 sensor(s). Returns true when no errors occur, and false if the wire is not present or some other error occurs | u8_devices: Number of probes connected (in parallel)1 | bool2 |
| fnDS18B20_Measure_Start_Blocking_Mode() | Begins a new temperature measurement, in blocking mode. | None | bool2 |
| fnDS18B20_Measure_Start_Callback_Mode() | Begins a new temperature measurement, in callback mode. | None | bool3 |
| fnDS18B20_Measure_Done_Callback() | This function gets called automatically after a measurement in callback mode is finished. | None | None |
| fnDS18B20_Get_Data_Pointer(uint8_t u8_channel) | Returns a const pointer to the struct that has all the raw data obtained, in the probe corresponding to u8_channel. Check the header for info on the struct. | u8_channel: Channel of the probe corresponding to the data pointer.4 | const st_ds18b20_data_t* |
| fnDS18B20_Get_Temperature(uint8_t u8_channel) | Returns a float in proper temperature format, in degrees Celsius. | None | float |
1It is possible to connect multiple DS18B20 probes at once, in parallel. The platform can handle up to 8 probes.
2Returns true when it ends without errors.
3Returns true after calling the Callback function.
4The probes' channels are addressed from 0 to 7. To be able to identify which probe is which, apart from manipulating the temperature and observing results, it is necessary to connect the probes one by one, identify their ROM ID using the Get_Data_Pointer function, by accessing the au8_rom_id integer present in this struct, and labelling each probe physically.
This is an emulated EEPROM, from within the board's Flash Memory.
Be aware that the maximum EEPROM size is 60 bytes. Any requests to read or write not within address values in 0-59 bytes will be ignored by the routine.
This module is initialized by default, hence there is no "Init" function.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnEEPROM_Get_Value(uint8_t u8_address) | Returns the contents of the specified address in the EEPROM. If the address is larger than the maximum memory address, returns 0xFF. | u8_address: Address of the content to access. | uint8_t |
| fnEEPROM_Set_Value(uint8_t u8_address, uint8_t u8_value) | Sets and readies a value to be written to a certain address in the EEPROM. | u8_address: The address to which the data is to be written. u8_value: The data to be written. |
None |
| fnEEPROM_Get_Value_Array(uint8_t u8_address) | Returns a 4-byte array of values, starting at the address specified. | u8_address: The starting address of the array | const uint8_t |
| fnEEPROM_Set_Value_Array(uint8_t u8_address, uint8_t * pu8_value, uint8_t u8_size) | Readies a byte array of a specific size to be written in the EEPROM memory. | u8_address: The starting address on which to store the array. pu8_value: The array variable you want to write in the EEPROM. u8_size: The size of said array. |
None |
| fnEEPROM_Commit() | Effectively writes to the emulated EEPROM, with the value and address set previously, in the Set_Value function. | None | None |
This header has functions for events that the system monitors. There are two possible methods to observe and make use of these events. A list of possible events is below the following tables.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnEVENT_Attach_Callback(en_event_t en_event, pfn_event_callback_t pfn_callback) |
Attaches a function to an event, so that the function will be called when the event occurs. | en_event: The event to be associated with the function pfn_callback: The function to be called when the event occurs |
bool1 |
| fnEVENT_Deattach_Callback (en_event_t en_event) | Deattaches any callback function associated with the event. | en_event: The event whose callbacks are to be detached. | bool1 |
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnEVENT_Callback(en_event_t en_event) | A function that gets called when any event occurs, and you can implement how it reacts to each one.2 | en_event: The event that occurred. | None |
The possible events are:
- EVENT_SYSTEM_NONE: A default event, never occurs.
- EVENT_SYSTEM_INIT: Occurs once at the bootup of the system.
- EVENT_SYSTEM_RTC: This event occurs every one (1) second, using the Real-Time Clock.
- EVENT_INPUT_BUTTON_PRESS: Occurs when the user button is pressed down.
- EVENT_INPUT_BUTTON_RELEASE: Occurs when the user button is released.
- EVENT_INPUT_BUTTON_PRESS_HOLD: When the user button is pressed and held down, this event occurs.
- EVENT_INPUT_BUTTON_RELEASE_HOLD: After being released, if the button isn't pressed again in a few moments, this event occurs. 3
- EVENT_INPUT_EXTERNAL_PRESS: When the analog input is configured to receive an external button, this event occurs when that button is pressed down.
- EVENT_INPUT_EXTERNAL_RELEASE: Same as the previous event, but when the button is released.
- EVENT_INPUT_EXTERNAL_PRESS_HOLD: Parallel to the user button PRESS_HOLD, when the external button is pressed and held down for a few moments, this event occurs.
- EVENT_INPUT_EXTERNAL_RELEASE_HOLD: This event occurs after the external button is released and not pressed again for a few moments.
1Returns true when the event is attached or deattached succesfully, and false when some error occurs.
2Unlike the attaching method, using this function you don't need to define and implement different functions to be called. They can all be inside the fnEVENT_Callback context. Check the Events Example in the Examples folder for a demonstration using Switch-Case.
3This event occurs once at the system's initialization as well.
This file contains functions to read both the integrated accelerometer and magnetometer in the EDK board.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnFXOS8700CQ_Init (en_fxos8700cq_operation_mode_t en_mode) |
Initializes the sensor for use. | en_mode: Determines with which mode the sensor should start.1 | bool2 |
| fnFXOS8700CQ_Enable() | Enables the sensor and makes a reading in whichever mode was set in Init. | None | None |
| fnFXOS8700CQ_Disable() | Disables the sensor, setting it into standby mode. | None | None |
| fnFXOS8700CQ_Get_Data_Pointer() | Returns a pointer to the register data, containing every raw measurement. | None | const st_fxos8700cq_data_t* |
| fnFXOS8700CQ_Get_Accel_Data() | Returns a pointer to a struct with data from the three axes from the accelerometer, in milli g-force | None | const st_fxos8700cq_converted_data_t3 |
| fnFXOS8700CQ_Get_Mag_Data() | Returns a pointer to a struct with data from the three axes from the magnetometer, in µT (micro Tesla) | None | const st_fxos8700cq_converted_data_t3 |
| fnFXOS8700CQ_CALLBACK_Measure_Done() | This function is called automatically when the measurement is properly complete. | None | None |
1Possible modes for the sensor to operate:
- FXOS8700CQ_OPERATION_MODE_MAG_ONLY: Magnetometer measurement only.
- FXOS8700CQ_OPERATION_MODE_ACCEL_ONLY: Accelerometer measurement only.
- FXOS8700CQ_OPERATION_MODE_HYBRID: Both sensors are measured.
2Returns true when the initialization occurs without error.
3This struct contains the following variables:
- int16_t i16_converted_x
- int16_t i16_converted_y
- int16_t i16_converted_z Depending on which function was called to return it, he struct will contain data for each axis of either the accelerometer or the magnetometer.
Be aware that not all EDK models include the 6-axis sensor. Please check which version you require prior to purchasing.
This header has the functions for the user button and the user-accessible LED.
By default these components are always initialized, eliminating the need for an Init() function.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnGPIO_LED_Set_Level(bool level) | Sets the LED level. | level: true for on, false for off. |
None |
| fnGPIO_LED_Toggle() | Toggles ("inverts") the current state of the LED. If on, turns it off; if off, turns it on. |
None | None |
| fnGPIO_Button_Get_Level() | Returns the current status of the user button. Returns false when the button is pressed down, and true when the button is unpressed, released. | None | bool |
The Real-Time Clock's header contains functions for measuring the amount of seconds that passed since initializing the component.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnRTC_Get_Count() | Returns the amount of seconds that passed since the RTC initialization. | None | uint32_t |
To implement a function that gets called every second, make use of the Events funcionality, attaching the RTC callback to whatever you need.
This component can read ambient light values, as well as the current UV index on the board.
In its header you'll find functions for measuring and reading such values.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnSI1133_Init() | Initializes the ambient light sensor. | None | bool1 |
| fnSI1133_Measure_Start_Blocking_Mode() | Begins a measurement in blocking mode, halting the program's execution until its completion. | None | bool2 |
| fnSI1133_Measure_Start_Callback_Mode() | Begins a measurement in callback mode, and calls the Done_Callback function when completed. | None | bool3 |
| fnDS18B20_Measure_Done_Callback() | This function is called automatically after the measurement started in callback mode is finished. | None | None |
| fnSI1133_Get_Data_Pointer() | Returns a pointer to the struct containing all the raw data obtained. | None | const st_si1133_data_t* |
| fnSI1133_Get_Lux() | Returns a float with the ambient light value, in Lux. | None | float |
| fnSI1133_Get_Uvi() | Returns a float with the current ambient UV index detected by the sensor. | None | float |
1Returns true when the initialization occurs without error.
2Returns true when the measurement finishes without error.
3Returns true after the callback function is called.
The SI7021 internal Temperature / Humidity sensor has functions for measuring and retrieving such data.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnSI7021_Init() | Initializes the sensor. | None | bool1 |
| fnSI7021_Start_Measure() | Begins a new measurement of both temperature and relative humidity. | None | bool2 |
| fnSI7021_CALLBACK_Measure_Done() | Function is called automatically when measurement is complete. | None | None |
| fnSI7021_Get_Temperature() | Returns the temperature measured. | None | int32_t |
| fnSI7021_Get_RH() | Returns the relative humidity measured. | None | uint32_t |
| fnSI7021_Get_Data_Pointer() | Returns a pointer to the full data structure, containing both the humidity and the temperature.3 | None | const st_si7021_data_t* |
1Returns true when the initialization occurs without error.
2Returns true after the CALLBACK function is called. We don't recommend using this function for anything other than starting a measurement.
3Check the header to see what the structure contains.
In this header are included functions for initializing the SIGFOX modem, and sending messages over its network. Also included are a few callbacks for successfull and failed transmissions, for messages both with or without receive confirmation from the server.
| Function | Description | Parameters | Return Type |
|---|---|---|---|
| fnRADIO_Init() | Initializes the SIGFOX modem, making it ready to transmit and receive. Returns false if some error occurs in initialization. | None | bool |
| fnRADIO_Send_Message (uint8_t * pu8_data, uint8_t u8_size, bool b_receive) |
Sends a message (max. size 12 characters) over the SIGFOX modem. Returns true when the process is finished, regardless of being successfully transmitted / received. | pu8_data: the data to be sent; u8_size: the size of the data to be transmitted; b_receive: true: server tries to send confirmation of receiving the message, false: server doesn't send confirmation. |
bool |
| fnRADIO_CALLBACK_Tx_End_Ok() | Gets called automatically whenever the system says there was a successful transmission, after the fnRADIO_Send_Message function is finished. | None | None |
| fnRADIO_CALLBACK_Tx_End_Error() | Gets called automatically whenever the system says there was an unsuccessful transmission.1 | None | None |
| fnRADIO_CALLBACK_Rx_End_Ok() | Called automatically when the server informs it received the message successfully.2 | None | None |
| fnRADIO_CALLBACK_Rx_End_Error() | Called automatically when the server informs some error while receiving the message.2 | None | None |
1 This may include serial communication errors, and whatever errors may occur before sending the message via the modem.
2 Only available when b_receive is set to true.
Be sure to be careful when sending messages over the SIGFOX Modem:
The messages will only be received if your device is registered within the SIGFOX network
The number of messages must be within the limits your contracted plan.
Receival confirmation is only available on some plans.
These functions are for communication using the USB Virtual COM Ports.
If you need to debug your program, include console_usb.h to activate the communication, and debug.h (both below) to send messages via UART Serial Communication.
This module is recommended to be disabled by default, to prioritize low-power consumption.
That being said, most of the examples use debugging to display data on a terminal, such as Tera Term, a great open-source terminal software that allows an easy connection to the USB COM Port.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnCONSOLE_USB_Init() | Initializes the USB Virtual COM Port for debugging and communication. | None | None |
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnDEBUG_Const_String (const char * p_char) |
Sends a const string to the terminal. | p_char: The const string to be sent. | None |
| fnDEBUG_String_Size (char * p_char, uint8_t size) |
Sends a string of a fixed size to the terminal. | p_char: The const string to be sent. size: The size of the string to be sent. |
None |
| 1fnDEBUG_Uint8_Value (const char * p_char , const uint8_t u8_data, const char * p_char_after) |
Sends a message to the terminal, containing a const string before, a value of unsigned 8-bit integer type, and a const string after. Useful for sending full messages. | p_char: The const string to be sent preceding the value. u8_data: The numerical value to be sent, in unsigned 8-bit integer type. p_char_after: A string sent to the terminal after the value. |
None |
| 1fnDEBUG_Int8_Value (const char * p_char , const int8_t u8_data, const char * p_char_after) |
Same as the previous function, except with a numerical value of signed 8-bit int type. | p_char: Same as previous function. u8_data: Value in signed 8-bit integer type. p_char_after: Same as previous function. |
None |
1These functions are also available for integers up to 32-bit values, both signed and unsigned. Simply replace the 8 with 16 or 32 in either function to send a 16 or 32-bit value, respectively.
The input connectors labeled "Therm" are meant to be used with thermocouple connectors. These components act as sturdy and reliable thermometers.
| Function | Description | Parameters | Return type |
|---|---|---|---|
| fnMCP9600_Init() | Initializes the MCP9600 thermocouple controller. | None | bool1 |
| fnMCP9600_Config (st_mcp9600_config_t * pst_mcp9600_config) |
Configures the thermocouple controller with a specific set of instructions, defined within the struct it receives. | pst_mcp9600_config: A struct containing all the configurations for the thermocouple controller. (more info below) | bool1 |
| fnMCP9600_Measure_Start_Blocking_Mode() | Starts a measurement in Blocking Mode. | None | bool1 |
| fnMCP9600_Measure_Start_Callback_Mode() | Starts a measurement in Callback Mode. | None | bool2 |
| fnMCP9600_Measure_Done_Callback() | This function is called automatically when a measurement in Callback Mode is complete. | None | None |
| fnMCP9600_Get_Data_Pointer() | Returns a pointer to the entire raw data struct obtained from the device. | None | const st_mcp9600_data_t |
| fnMCP9600_Get_Temperature() | Returns an int32_t with the temperature value measured in the thermocouple, in hundreds of degrees celsius. You have to divide the resulting value by a factor of 100 to obtain the correct decimal value in degrees celsius. | None | int32_t |
1Returns true when the function finishes without error.
2Returns true after the Measure_Done_Callback function is called successfully.
The pst_mcp9600_config struct contains four (4) enumerations with parameters that must be established:
| Enumeration | Description | Options |
|---|---|---|
| en_adc_res_bits | Resolution of the Analog-Digital conversion, ranging from 12 to 18 bits. | MCP9600_ADC_MEASUREMENT_RESOLUTION_18_BITS MCP9600_ADC_MEASUREMENT_RESOLUTION_16_BITS MCP9600_ADC_MEASUREMENT_RESOLUTION_14_BITS MCP9600_ADC_MEASUREMENT_RESOLUTION_12_BITS |
| en_cold_junction_res | Resolution of the cold junction measurement. | MCP9600_COLD_JUNCTION_RESOLUTION_0_0625 MCP9600_COLD_JUNCTION_RESOLUTION_0_25 |
| en_filter_coefficients | The coefficients of the chosen filter. Check the MCP9600 page and datasheet for more information to choose the correct filter. |
MCP9600_FILTER_0 through MCP9600_FILTER_7 |
| en_thermocouple_type | Type of thermocouple used. | MCP9600_TYPE_K MCP9600_TYPE_J MCP9600_TYPE_T MCP9600_TYPE_N MCP9600_TYPE_S MCP9600_TYPE_E MCP9600_TYPE_B MCP9600_TYPE_R |
Check our Thermocouple Example for an example of how to set these parameters.
Please be aware that not all EDK models include the Thermocouple controller and its input connectors. Please check which version you require prior to purchasing.
- uDEV website
- uDEV EDK at SIGFOX Partners
- Atmel Studio download page
- Microchip SAM-BA download page
- Tera Term download page (An open-source serial/tcp terminal software)