Astarte device API for Zephyr 0.7.1
Astarte device SDK for Zephyr RTOS
|
Astarte device library for the Zephyr framework.
Before getting started, make sure you have a proper Zephyr development environment. Follow the official Zephyr Getting Started Guide.
To add this module as a dependency to an application the application's west.yml
manifest file should be modified in the following way. First, a new remote should be added:
Second, a new entry should be added to the projects list:
Remember to run west update
after performing changes to the manifest file.
In addition, the Astarte device library Kconfig
should be added to the Kconfig
file of the application.
This will add the configuration options of the example module to the application.
For development or evaluation purposes the library can be used as a stand alone application in its own workspace. This will make it possible to build and execute the module samples without having to set up an extra application.
Start by creating a new workspace folder and a venv where west
will reside. Then clone this library inside the newly created workspace.
The west workspace should be then intialized, using the example repository as the manifest repository.
Lastly some dependencies will need to be installed for all west extensions to work correctly.
If building for an esp32 the binary blobs will need to be downloaded before building the application.
Note: this command should be re-run when updating Zephyr to a newer version
To build one of the samples applications, run the following command:
Where <BOARD>
is one of the boards supported by Zephyr and <SAMPLE>
is one of the samples contained in the samples
folder.
Once you have built the application, run the following command to flash it on the ESP board:
Or the following command to run on an emulated board or the native simulator:
While usually the configuration setting are set in a prj.conf
file, during development it might be useful to set them manually. To do so run the following command:
This command will require the application to have already been build to function correctly. After changing the configuration, the application can be flashed directly using west flash
.
The standard configuration for all the samples include settings for printing the logs through the serial port connected to the host.
A set of unit test is present under the tests
directory of this project. They can be run using twister.
The standard format of an Astarte interface is a JSON file as defined in the Astarte documentation. However, an Astarte device on Zephyr uses C structures to define Astarte interfaces. Translating an interface from a JSON definition to a C definition for Zephyr can be a repetitive and error-prone process.
For this reason, an extension command for west
has been created to facilitate this procedure. The generate-interfaces
extension command accepts as input one or more JSON interface definitions and automatically generates the corresponding C source code. Run west generate-interfaces --help
to learn about the generation options.
It's also possible to automatically generate the interface definition structs. Generated files will be located in the build directory: build/zephyr/include/generated/astarte_generated_interfaces.*
.
This allows an easier management of generated files that won't need to be committed to the vcs. Enabling the feature is straight forward and requires setting two configuration values in the project prj.conf
file:
Replace <interface jsons directory>
with the relative path to the interfaces directory.
After adding the two properties you can run a build targeting astarte_generate_interfaces
.
or simply launch a build of the project.
After this you'll be able to include the generated header file:
For a complete example you can take a look at e2e/prj.conf
and the interfaces/
directory. The generated interfaces are included in e2e/src/runner.c
.
The code in this module is formatted using clang-format
. An extension command for west
has been created to facilitate formatting. Run west format --help
to learn about the formatting options.
CodeChecker is the one of the two natively supported static analysis tools in west
. It can be configured to run different static checkers, such as clang-tidy
and cppcheck
.
An extension command for west
has been created to facilitate running static analysis with clang-tidy
. Run west static --help
to read what this command performs.
The dependencies for generating the doxygen documentation are:
doxygen <= 1.9.6
graphviz
An extension command for west
has been created to facilitate generating the documentation. Run west docs --help
for more information on how to generate the documentation.
Here are some quick tips to configure VS Code with a Zephyr workspace. Make sure the following extensions are installed:
Create the file ./.vscode/settings.json
and fill it with the following content:
The first setting will avoid noisy popups from the CMake extension. The python related settings will ensure that each time the integrated terminal is open, the venv containing west
will be automatically activated. The C/C++ settings will configure intellisense. Those setting might be slightly different for your specific Zephyr SDK installation as versions might change. Also, the compile commands path assumes west build
gets run from the root of the zephyr workspace.
Some additional documentation for the library architecture is available.