Caution
The tosca framework is in a very early, experimental stage of development.
The APIs are still unstable and subject to change.
Be aware that even a minor version may introduce API breakages.
A major version will be released only when the APIs remain stable and
unchanged for an extended period.
This approach aims to provide clearer and more precise APIs, shaped by user
feedback and suggestions during the initial stages of the project.
tosca is a versatile, customizable, and secure IoT framework.
-
Versatile: The framework offers APIs to develop firmware for various hardware architectures, supporting both bare-metal and OS-based devices. At the same time, it also supplies APIs for creating software that interacts with the firmware of these devices.
-
Customizable: Most of the APIs are designed as a sequence of code blocks, where each block represents a single feature or a set of features. These blocks can be combined by adding or removing lines of code. For example, if your device supports events, you only need to integrate the event APIs into your firmware server to send the data to its controller. If your firmware does not use events, there is no need to touch those APIs.
-
Secure: Written in Rust, a language renowned for its emphasis on performance and reliability. Its rich type system and ownership model guarantees memory and thread safety, preventing many classes of bugs at compile-time.
The framework revolves around the tosca interface, which connects two sides
of the framework. The first is the Firmware Side, responsible for developing
firmware and providing drivers for sensors, while the second is the
Controller Side, responsible for interacting with the devices built using
the tosca framework.
tosca is the main crate of the framework. It serves as an interface between a device and a controller.
It can:
- Create and manage REST routes to issue commands from a
controller to a device. Each route can even define parameters that mirror
those used by a device in its operations. The responses to a route can include
a simple
Okindicating success on the device side, aSerialresponse with additional data about the device operation, and anInforesponse containing metadata and other details about the device. TheStreamresponse is optional and can be enabled via a feature, delivering chunks of multimedia data as bytes. - Describe a device, including the structure of its firmware, its internal data and methods, as well as information about its resource consumption at the economic and energy levels.
- Associate hazards with a route to describe the risks of a device operation. A hazard is categorized into three types: Safety, Financial, or Privacy. The Safety category covers risks to human life, the Financial category addresses the economic impacts, and the Privacy category relates to issues concerning data management.
It offers several features that reduce the final binary size and speed up
compilation.
The stream feature enables all data and methods necessary to identify a
multimedia stream sent from a device to a controller.
The deserialize feature enables data deserialization, which is generally
useful for controllers but not for devices, as they typically handle only
serialization.
To ensure compatibility with embedded devices, this library is no_std, linking
to the core crate instead of the std crate.
The tosca-os
and
tosca-esp32c3
crates are two libraries used for building firmware. As previously stated, they
integrate the tosca library as a dependency in their APIs to maintain a
common interface.
The tosca-os library crate is designed for firmware running on operating
systems.
In the tosca-os/examples directory, you will find a simple example of both light and IP-camera firmware.
The tosca-esp32c3 library crate is designed for firmware running on
ESP32-C3 microcontrollers.
In the tosca-esp32c3/examples directory, you will find several light firmware examples
demonstrating various features of this library.
The tosca-drivers
library crate provides architecture-agnostic drivers for a range of sensors
and devices. All drivers are built on top of embedded-hal and
embedded-hal-async, ensuring compatibility across all supported
hardware platforms.
The tosca-controller library crate defines a set of APIs for managing, orchestrating, and interacting with firmware built using the crates mentioned above. In the tosca-controller/examples directory, you will find some examples demonstrating various methods for receiving events from devices.
The framework repository is a Cargo
workspace composed of several crates. Dependencies common to all crates are
defined in the root Cargo.toml, ensuring they are compiled once and their
resulting binaries shared across all crates.
The same approach is applied to the tosca metadata.
To build the entire workspace with the debug profile from the root of the
repository, run:
cargo buildTo build the entire workspace with the release profile, which enables all time
and memory optimizations, run the following command from the root of the
repository:
cargo build --releaseTo build a specific crate, navigate to its corresponding subdirectory within the crates directory and run the same build commands as described above.
If a crate provides features that you want to disable, add the
--no-default-features option to the commands above.
Note
The tosca-esp32c3 library crate is not part of the workspace and must be
built separately, as it targets a specific architecture
(riscv32imc-unknown-none-elf), requiring a specialized build process.
The per-package-target
feature in Cargo is unstable and only available on the nightly toolchain.
To run the full test suite for each crate, execute the following command:
cargo testThis may take several minutes, depending on the tests defined in each crate.
If only the tests for a specific crate need to be run, navigate to the
corresponding crate subdirectory and execute the cargo test command.
If a crate provides features that you want to disable, add the
--no-default-features option to the commands above.
Licensed under either of
at your option.
Contributions are welcome via pull request. The Rust Code of Conduct applies.
Unless explicitly stated otherwise, all contributions will be licensed under the project defined licenses, without any additional terms or conditions.