Ruuvi embedded drivers used across various platforms. Generally you should not use this repository as-is, but rather as a submodule included in your project.
Version 3.4.0 and upwards are considered stable and no breaking changes will be introduced to interfaces or tasks, i.e. no unit test or integration test is changed or deleted without updating the major version. Non-tested functionality and failing tests are subject to change.
The drivers project has other drivers - suchs as Bosch and STM official drivers - as submodules at root level.
Ruuvi code is under src folder.
Interfaces folder provides platform-independent access to the peripherals of the
underlying microcontroller, for example function
int8_t spi_bosch_platform_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *data, uint16_t len);
is defined, but not implemented. This eases mocking the tasks for unit tests.
Implementation of interfaces is in *_platform-folders.
Currently only supported platform is Nordic SDK15.3. Unpack (or softlink) the SDK on the root of the project for running the tests.
Because the platforms must contain hardware dependencies, the interfaces and platforms which implement them are not unit tested but integration tested instead.
Tasks are larger functionalities, such as "get battery voltage" or "Broadcast this data". To keep the tasks unit testable, they must contain only references to interfaces which allows mocking the hardware dependencies.
Files should be named ruuvi_module_name, for example ruuvi_interface_spi.h
Globally visible functions, variables and definitions should be likewise named with
abbreviation of ruuvi_type_module_name, for example ri_yield_init() or
rt_adc_vdd_get()
The application should contain app_config.h which includes platform specific includes
such as nrf5_sdk15_app_config.h. Preprocessor must define APPLICATION_DRIVER_CONFIGURED
to let drivers know they can include the app_config.h and RUUVI_NRF5_SDK15_ENABLED
for including the nrf5_sdk15_app_config.h.
As the repository may contain several different implementations of interface functions the
desired implementation is enabled by definining PLATFORM_MODULE_ENABLED 1,
for example RUUVI_NRF5_SDK15_LOG_ENABLED 1.
Leaving unused modules unenabled will conserve some flash and RAM as they're not linked into given application.
There are common error code definitions for the drivers, please see ruuvi_driver_error.h for details.
Sensors have a common interface which has setter and getter functions for common parameters such as scale, resolution, sample rate and dsp function. Initialization function takes a pointer to sensor interface type, as well as used bus (I2C or SPI) and a handle which helps firmware to select the desired on board. On SPI the handle is GPIO pin of Chip Select, on I2C the handle is I2C address of the sensor.
All sensors have ri_sensor_init(rd_sensor_t*, rd_bus_t, uint8_t) function which must be called before usage. Check the interface definition of detailed explanation of any initialization parameters.
- rd_sensor_t* is a pointer to sensor struct which will get initialized with proper function pointers
- bus is the bus being used for sensor, such as I2C, SPI or NONE for MCU internal peripherals
- uint8_t is a handle for the sensor. For I2C it's the device address, for SPI it's GPIO which controls the peripheral sensor and for NONE it could be e.g. ADC channel.
- Sensor must return RD_SUCCESS on first init.
- None of the sensor function pointers may be NULL after init
- Sensor should return RD_ERROR_INVALID_STATE when initializing sensor which is already init. Sensor may return other error if check for it triggers first.
- Sensor must return RD_SUCCESS on first uninit
- All of sensor function pointers must be NULL after uninit
- Sensor must be in lowest-power state possible after init
- Sensor must be in lowest-power state available after uninit.
- Sensor configuration is not defined before init and after uninit
- Sensor initialization must be successful after uninit.
- Init and Uninit must return RD_ERROR_NULL if pointer to the sensor struct is NULL.
Run doxygen.
Run astyle --project=.astylerc ./target_file. To format the entire project,
astyle --project=.astylerc --recursive "./interfaces/*.c"
astyle --project=.astylerc --recursive "./interfaces/*.h"
astyle --project=.astylerc --recursive "./nrf5_sdk15_platform/*.c"
astyle --project=.astylerc --recursive "./nrf5_sdk15_platform/*.h"
Or just make astyle
Unit tests are run by Ceedling and they are completely hardware-independent.
They can be run by e.g. Travis. The unit tests are in test folder.
Integration tests are run on actual hardware and cannot be run on the cloud.
Integration tests are in src/integration_tests folder. Application should run the
integration tests.
System testing and acceptance testing are in the scope of main application and not handled here.
All Ruuvi code is BSD-3 licensed. Drivers from other sources (as git submodules) have their own licenses, please check the specific submodule for details. Platforms have license of the platform providers, for example Nordic semiconductor platform files follow Nordic SDK License.
All contributions are welcome, from typographical fixes to feedback on design and naming schemes. If you're a first time contributor, please leave a note saying that BSD-3 licensing is ok for you.
See CHANGELOG.md