5387c20dde
This changes the API of nanocoap with the goal to reduce the expose of
UDP specifics in the API. The plan is to eventually support transports
such as CoAP over TCP and CoAP over WebSocket directly in nanocoap
while sharing most of the code, as e.g. the CoAP Option processing
remains identical. Specifically, the plan is to unlock a transport with
modules and introduce overhead for dispatching to specific transport
only when multiple transports are actually in use.
Support for OSCORE directly in nanocoap is probably not sensible, as
the serialization is very much unlike the other transports. A unified
CoAP API for multiple transports including OSCORE is probably best
implemented on top. But when limited to the boring set of CoAP
transports, we probably can support them well with nanocoap with less
overhead.
Breaking API Changes:
=====================
- `coap_parse()` now returns `ssize_t` instead of `int`
- This function is not really user facing, so the impact should
be limited
- This is useful for stream transports where the buffer may
contain data of more than one packet. The return value contains
the number of bytes actually consumed, which will match the
buffer size for non-stream transports.
API Changes:
============
- `coap_pkt_t` now contains a `uint8_t *buf` pointer instead of a
`coap_hdr_t *hdr` pointer to the beginning of the buffer
- This will also work when the buffer is used by non-UDP
transports
- A deprecated `coap_udp_hdr_t *hdr` has been crammed into
an unnamed `union` with `uint8_t *buf`. For architectures
where pointers have the same memory layout regardless of type
(e.g. all of the supported ones), this will make `hdr` an
alias for `buf`.
- The alias will only be provided if no transport besides UDP is
used in nanocoap. So existing apps will continue to work, new
apps that want to support other transports need to move to
adapt.
- `coap_hdr_t` has been renamed to `coap_udp_hdr_t`
- A deprecated alias was created for deprecation
- `coap_hdr*()` functions have been deprecated
- Equivalent `coap_pkt*()` functions have been created that work
on `coap_pkt_t *` instead of `coap_hdr_t *`
- If non-UDP transports are used, the deprecated `coap_hdr*()`
will probably not be exposed to avoid footguns.
- `coap_build_hdr()` has been renamed to `coap_build_udp_hdr()` and
that works on an `uint8_t *` buffer with a given length, rather than
on a `coap_hdr_t *` with a *figers crossed* length
- a deprecated `coap_build_hdr()` function was added that calls
to `coap_build_udp_hdr()` and has the same signature, so that
users have time to update
RIOT OS: The friendly Operating System for IoT!
RIOT is an open-source microcontroller operating system, designed to match the requirements of Internet of Things (IoT) devices and other embedded devices. It supports a range of devices that are typically found in the Internet of Things (IoT): 8-bit, 16-bit and 32-bit microcontrollers.
RIOT is based on the following design principles: energy-efficiency, real-time capabilities, small memory footprint, modularity, and uniform API access, independent of the underlying hardware (this API offers partial POSIX compliance).
RIOT is developed by an international open source community which is independent of specific vendors (e.g. similarly to the Linux community). RIOT is licensed with LGPLv2.1, a copyleft license which fosters indirect business models around the free open-source software platform provided by RIOT, e.g. it is possible to link closed-source code with the LGPL code.
Getting Started
- Start here: Our comprehensive Getting Started Guide walks you through installation and your first RIOT applications.
- Learn by doing:
- Try our hands-on tutorials designed for beginners
- Take the RIOT online course at your own pace
- Explore the API: Check out the API documentation for detailed information on RIOT's features and functions.
Features
RIOT provides features including, but not limited to:
- Platforms Supported
- 200+ boards based on AVR, MSP430, ESP8266, ESP32, RISC-V, ARM7, and ARM Cortex-M
- The native port allows to run RIOT as-is on Linux and BSD. Multiple instances of RIOT running on a single machine can also be interconnected via a simple virtual Ethernet bridge or via a simulated IEEE 802.15.4 network (ZEP).
- Programming Environment
- Write native code in C, C++, or Rust
- Rely upon POSIX APIs, user friendly hardware abstractions and standard embedded Rust interfaces
- Integrate dynamic runtimes such as MicroPython, elm (JavaScript) and WASM
- Network Features and Protocols
- IPv6
- IPv4 via lwIP
- 6LoWPAN (RFC4944, RFC6282, RFC6775 and RFC7668)
- UDP
- TCP
- RPL (storing mode, P2P mode)
- CoAP
- MQTT via paho-mqtt and MQTT-SN
- LwM2M
- Bluetooth (BLE) via NimBLE
- LoRaWAN
- UWB
- CAN
- CNN-Lite
- LwIP
- IEEE 802.15.4
- Ethernet (also via USB)
- SLIP (or ethos networking via Serial)
- Dose (single pair ethernet like networking on serial interface UART)
- System Features
- a preemptive, tickless scheduler with priorities, optional periodic round robin within priorities
- flexible memory management
- high resolution, long-term timers
- MTD abstraction layer for memory devices
- File System integration
- Security Features
- OTA updates via SUIT
- PSA Cryptographic API
- DTLS, EDHOC
- Device Drivers
- SPI, I2C, UART, USB, CAN
- RTC, PWM, Timer
- ADC, DAC
- Various sensors: Environmental sensors, IMUs, magnetometers, particulate matter sensors
- Various actuators: Servos, motors, dimmers, switches, RGB LEDs
- Displays and touchscreens
- GNSS
Community
You can ask for help on the Forum or on Matrix. Please send bug reports and feature requests to our GitHub issue tracker
- The Forum is the default place to start asking for help. Our Forum provides an archive of prior questions and answers.
- For chat, we use #riot-os:matrix.org on the Matrix chat network.
Governance
For how our community is structured and governed, please see our governance document.
How to Ask
Please include as much detail as you can that is relevant to your question, not only "this isn't working". These details include:
- What you want to achieve.
- What have you tried so far (for example the commands you typed).
- What happened so far.
Collaboration
RIOT closely collaborates with and inspires other open source projects, e.g., Ariel OS, an IoT OS written in Rust. We are more than happy to collaborate with those who share our vision.
Getting RIOT
The most convenient way to get RIOT is to clone it via Git
$ git clone https://github.com/RIOT-OS/RIOT
this will ensure that you get all the newest features and bug fixes with the caveat of an ever changing work environment.
If you prefer things more stable, you can download the source code of one of our quarter annual releases via Github as ZIP file or tarball. You can also checkout a release in a cloned Git repository using
$ git pull --tags
$ git checkout <YYYY.MM>
For more details on our release cycle, check our documentation.
Contribute
To contribute something to RIOT, please refer to our contributing document.
Mailing Lists
- Github notifications: notifications@riot-os.org
License
- Most of the code developed by the RIOT community is licensed under the GNU Lesser General Public License (LGPL) version 2.1 as published by the Free Software Foundation.
- Some external sources, especially files developed by SICS are published under a separate license.
All code files contain licensing information.
For more information, see the RIOT website.