Skip to content

AVSystem/Anjay

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

BREAKING CHANGES:
- Observations are now implicitly canceled when the client's endpoint identity changes (i.e., when the socket is reconnected without a successful DTLS session resumption). This is in line with [RFC 7641](https://datatracker.ietf.org/doc/html/rfc7641#page-22) and LwM2M TS requirements (see [Core 6.4.1](https://www.openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/HTML-Version/OMA-TS-LightweightM2M_Core-V1_1_1-20190617-A.html#6-4-1-0-641-Observe-Operation) and [Transport 6.4.3](https://www.openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/HTML-Version/OMA-TS-LightweightM2M_Transport-V1_1_1-20190617-A.html#6-4-3-0-643-Registration-Interface)), but may break compatibility with some non-well-behaved servers.

Features:
- New APIs to access information about the last registration time, next registration update time and last communication with a server time
- Expanded anjay_resource_observation_status_t structure so that now anjay_resource_observation_status() returns also the number of servers that observe the given Resource (capped at newly introduced ANJAY_MAX_OBSERVATION_SERVERS_REPORTED_NUMBER) and their SSIDs

Improvements:
- Migrated GitHub Actions tests from Fedora-36 to RockyLinux-9
- Added compilation flag to enforce Content-Format in Send messages.
- Refactored Firmware Update notification handling and simplified internal module support
- Removed the usage of symbolic links between Python packages to make them usable on Windows
- Key generation in the factory provisioning script has been rewritten to use the cryptography Python module instead of pyOpenSSL
- Factory provisioning script now uses elliptic curve cryptography by default in certificate mode
- anjay_next_planned_lifecycle_operation() and anjay_transport_next_planned_lifecycle_operation() now properly respect jobs that have been scheduled manually (e.g. anjay_schedule_registration_update())

Bugfixes:
- Fixed a bug that could cause some resources in a Write message to be ignored when they follow a Multiple-Instance Resource entry
- Fixed semantics of Resources 19 and 20 in the Server object, which were mistakenly swapped
  - NOTE: The persistence format for the Server object has been reinterpreted so that Resources 19 and 20 remain where they were, without taking semantics into account. This will fix configurations provisioned by Servers but may break configuration persisted just after initially configuring it from code.
- Made sure that anjay_schedule_registration_update() forces a single Update request even when followed by anjay_transport_schedule_reconnect() or a change of offline mode
- Made sure that notifications are not sent before the Update operation if one has been scheduled
- Made sure that anjay_transport_schedule_reconnect() properly reconnects the Bootstrap server connection in all cases
- Made sure that the socket is properly closed when queue mode is enabled, including previously missing cases related to the Send operation and when no CoAP message needs to be sent at all
- Refactored asynchronous server connection management to avoid race conditions that could lead to required actions (e.g. EST requests) not being performed when the calculated delays were not big enough
41c7aef

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
May 18, 2022
Dec 7, 2022
Dec 7, 2022
doc
Dec 7, 2022
Aug 24, 2022
src
Dec 7, 2022
Dec 7, 2022
Dec 7, 2022
May 18, 2022
Mar 19, 2021
May 18, 2022
Nov 23, 2020
Dec 7, 2022
May 18, 2022
Dec 7, 2022
May 18, 2022
Aug 24, 2022
May 18, 2022

Anjay LwM2M library

Build Status Coverity Status

New license notice

With release of Anjay 3.0, the library's license terms have changed. Please make sure that you have reviewed it before updating to the new major release. Previous versions of Anjay remain with the old, Apache 2.0 license.

What is Anjay?

Anjay is a C library that aims to be the reference implementation of the OMA Lightweight Machine-to-Machine (LwM2M) device management protocol. It eases development of fully-featured LwM2M client applications by taking care of protocol details, allowing the user to focus on device-specific aspects.

The project has been created and is actively maintained by AVSystem.

Supported features

This version includes full support for OMA LwM2M TS 1.1 features. Some features, such as support for EST, SMS binding or HSM's are available commercially.

  • LwM2M Bootstrap Interface:

    • Request
    • Discover
    • Read
    • Write
    • Delete
    • Finish
  • LwM2M Client Registration Interface:

    • Register
    • Update
    • De-register
  • LwM2M Device Management and Service Enablement Interface:

    • Discover
    • Read
    • Read-Composite
    • Write
    • Write-Composite
    • Execute
    • Write-Attributes
    • Create
    • Delete
    • Send
  • LwM2M Information Reporting Interface:

    • Observe
    • Observe-Composite
    • Cancel Observation
    • Cancel Observation-Composite
    • Notify
  • LwM2M Security modes:

    • DTLS with Certificates (if supported by backend TLS library)
    • DTLS with PSK (if supported by backend TLS library)
    • NoSec mode
  • Supported TLS backends:

    • mbed TLS
    • OpenSSL
    • tinydtls
  • Supported platforms:

  • CoAP data formats:

    • Plain Text
    • Opaque
    • CBOR
    • TLV
    • SenML JSON
    • SenML CBOR
    • LwM2M JSON (output only)
  • CoAP BLOCK transfers (for transferring data that does not fit in a single UDP packet):

    • Block1 (sending / receiving requests)
    • Block2 (sending responses)
  • Pre-implemented LwM2M Objects:

    • Access Control
    • Security
    • Server
    • Firmware Update
    • IPSO single and three-axis sensor objects
  • Stream-oriented persistence API

About OMA LwM2M

OMA LwM2M is a remote device management and telemetry protocol designed to conserve network resources. It is especially suitable for constrained wireless devices, where network communication is a major factor affecting battery life. LwM2M features secure (DTLS-encrypted) methods of remote bootstrapping, configuration and notifications over UDP or SMS.

More details about OMA LwM2M: Brief introduction to LwM2M

Quickstart guide

Dependencies

  • C compiler with C99 support,
  • avs_commons - included in the repository as a subproject,
  • If DTLS support is enabled, at least one of:
  • Optional dependencies (required for tests):
  • Optional dependencies (required for building documentation - more information in "Contributing" section):

Ubuntu 18.04 LTS / Raspbian Buster or later

sudo apt-get install git build-essential cmake libmbedtls-dev zlib1g-dev

CentOS 7 or later

# EPEL is required for mbedtls-devel and cmake3
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install -y which git make cmake3 mbedtls-devel gcc gcc-c++ zlib-devel

macOS Sierra or later, with Homebrew

brew install cmake mbedtls openssl

Running the demo client

For initial development and testing of LwM2M clients, we recommend using the Coiote IoT Device Management where you can use the basic LwM2M server functionality for free.

After setting up an account and adding the device entry, you can compile Anjay demo client and connect it to the platform by running:

git clone https://github.com/AVSystem/Anjay.git \
    && cd Anjay \
    && git submodule update --init \
    && cmake . \
    && make -j \
    && ./output/bin/demo --endpoint-name $(hostname) --server-uri coap://eu.iot.avsystem.cloud:5683

NOTE: On some older systems like CentOS 7, you may need to use cmake3 instead of cmake.

NOTE: We strongly recommend replacing $(hostname) with some actual unique hostname. Please see the documentation for information on preferred endpoint name formats. Note that with the Coiote IoT Device Management platform, you will need to enter the endpoint name into the server UI first.

Detailed compilation guide

First, make sure all necessary submodules are downloaded and up-to-date:

git submodule update --init

After that, you have several options to compile the library.

Building using CMake

The preferred way of building Anjay is to use CMake.

By default demo client compiles with DTLS enabled and uses mbedtls as a DTLS provider, but you may choose other DTLS backends currently supported by setting DTLS_BACKEND in a CMake invocation to one of the following DTLS backends: openssl, mbedtls or tinydtls:

cmake . -DDTLS_BACKEND="mbedtls" && make -j

Or, if a lack of security (not recommended) is what you need for some reason:

cmake . -DDTLS_BACKEND="" && make -j

Compiled executables, including demo client, can be found in output/bin subdirectory.

For a detailed guide on configuring and compiling the project (including cross-compiling), see Compiling client applications.

To start the demo client:

# uses plain CoAP
./output/bin/demo --endpoint-name $(hostname) --server-uri coap://eu.iot.avsystem.cloud:5683

# uses DTLS in PSK mode, with PSK identity "foo" and secret key "bar" (hex-encoded)
./output/bin/demo --endpoint-name $(hostname) --server-uri coaps://eu.iot.avsystem.cloud:5684 --security-mode psk --identity 666f6f --key 626172

NOTE: When establishing a DTLS connection, the URI MUST use "coaps://". In NoSec mode (default), the URI MUST use "coap://".

Alternative build systems

Alternatively, you may use any other build system. You will need to:

  • Prepare your avs_commons_config.h, avs_coap_config.h and anjay_config.h files.
  • Configure your build system so that:
    • At least all *.c and *.h files from src, include_public, deps/avs_coap/src, deps/avs_coap/include_public, deps/avs_commons/src and deps/avs_commons/include_public directories are preserved, with the directory structure intact.
      • It is also safe to merge contents of all include_public directories into one. Merging src directories should be safe, too, but is not explicitly supported.
    • All *.c files inside src, deps/avs_coap/src, deps/avs_commons/src, or any of their direct or indirect subdirectories are compiled.
    • deps/avs_commons/src and deps/avs_commons/include_public directories are included in the header search path when compiling avs_commons.
    • deps/avs_coap/src, deps/avs_coap/include_public and deps/avs_commons/include_public directories are included in the header search path when compiling avs_coap.
    • src, include_public, deps/avs_coap/include_public and deps/avs_commons/include_public directories are included in the header search path when compiling Anjay.
    • include_public, deps/avs_coap/include_public and deps/avs_commons/include_public directories, or copies of them (possibly merged into one directory) are included in the header search path when compiling dependent application code.

Below is an example of a simplistic build process, that builds all of avs_commons, avs_coap and Anjay from a Unix-like shell:

# configuration
cp -r example_configs/linux_lwm2m10 config
# you may want to edit the files in the "config" directory before continuing

# compilation
cc -Iconfig -Iinclude_public -Ideps/avs_coap/include_public -Ideps/avs_commons/include_public -Isrc -Ideps/avs_coap/src -Ideps/avs_commons/src -c $(find src deps/avs_coap/src deps/avs_commons/src -name '*.c')
ar rcs libanjay.a *.o

# installation
cp libanjay.a /usr/local/lib/
cp -r include_public/avsystem /usr/local/include/
cp -r deps/avs_coap/include_public/avsystem /usr/local/include/
cp -r deps/avs_commons/include_public/avsystem /usr/local/include/
cp -r config/* /usr/local/include/

Use a Dockerfile

For some cases you may find it comfortable to use Docker image. In this case, the only dependency is Docker, which you can install with your favorite package manager. If Docker is already installed, you can clone the repo and build the Docker image:

git clone --recurse-submodules https://github.com/AVSystem/Anjay.git
cd Anjay
docker build --no-cache --tag anjay .

Then, you can launch the built image and run the demo client:

docker run -it anjay
./output/bin/demo -e $(hostname) -u coap://eu.iot.avsystem.cloud:5683

Embedded operating systems ports

If you want to use Anjay on Mbed OS, Zephyr OS, FreeRTOS or ESP-IDF check our demo applications available in other repositories:

Raspberry Pi client

LwM2M Client for Raspberry Pi, with a feature allowing for implementing LwM2M Objects in Python, is available in Svetovid-raspberry-client repository.

Java bindings

Maven Central repository contains anjay-java and anjay-android artifacts which allow to use Anjay in Java applications.

In case of using anjay-java, check Anjay-java repository for details how to compile the native library. This step isn't required if you want to use anjay-android in your Android application.

License

See LICENSE file.

Commercial support

Anjay LwM2M library comes with the option of full commercial support, provided by AVSystem.

The list of features available commercially is available here.

If you're interested in LwM2M Server, be sure to check out the Coiote IoT Device Management platform by AVSystem. It also includes the interoperability test module that you can use to test your LwM2M client implementation. Our automated tests and testing scenarios enable you to quickly check how interoperable your device is with LwM2M.

Contributing

Contributions are welcome! See our contributing guide.

Building documentation

Make sure, both Doxygen and Sphinx are installed on your system, then type:

cmake . && make doc

the documentation will be available under output/doc/doxygen and output/doc/sphinx.