Anjay LwM2M library

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
About OMA LwM2M
Quickstart guide
License
- Commercial support
Contributing

Supported features

LwM2M Bootstrap Interface:
- Request
- Finish
- Write
- Delete
- Discover
LwM2M Client Registration Interface:
- Register
- Update
- De-register
LwM2M Device Management and Service Enablement Interface:
- Read
- Discover
- Write
- Write-Attributes
- Execute
- Create
- Delete
LwM2M Information Reporting Interface:
- Observe
- Notify
- Cancel Observation
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
CoAP data formats:
- TLV
- Opaque
- Plain Text (including base64 encoding of opaque data)
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
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,
CMake 2.8.11+,
avs_commons - included in the repository as a subproject,
If DTLS support is enabled, at least one of:
- OpenSSL 1.1+,
- mbed TLS 2.0+,
- tinydtls 0.9+,
Optional dependencies (required for tests):
- C++ compiler with C++11 support,
- Python 3.5+,
- pybind11 - included in the repository as a subproject,
- scan-build - for static analysis.

Ubuntu 16.04 LTS

sudo apt-get install git build-essential cmake libmbedtls-dev zlib1g-dev
# Optionally for tests:
sudo apt-get install libpython3-dev libssl-dev python3 python3-cryptography python3-jinja2 python3-sphinx python3-requests clang valgrind clang-tools
pip3 install grequests

CentOS 7

# Required for mbedtls-devel and python3.5
sudo yum install -y https://centos7.iuscommunity.org/ius-release.rpm
sudo yum install -y which git make cmake mbedtls-devel gcc gcc-c++

# Optionally for tests:
sudo yum install -y valgrind valgrind-devel openssl openssl-devel python35u python35u-devel python35u-pip python-sphinx python-sphinx_rtd_theme clang-analyzer
# Some test scripts expect Python >=3.5 to be available via `python3` command
# Use update-alternatives to create a /usr/bin/python3 symlink with priority 0
# (lowest possible)
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.5 0
sudo python3 -m pip install cryptography jinja2 requests grequests

macOS Sierra with Homebrew

brew install cmake mbedtls
# Optionally for tests:
brew install python3 openssl llvm
pip3 install cryptography sphinx sphinx_rtd_theme requests grequests

Windows

Windows support is currently in a preliminary stage. See README.Windows.md for details.

Running the demo client

To compile Anjay demo client and connect it to a local LwM2M server listening on default 5683 port:

git clone https://github.com/AVSystem/Anjay.git \
    && cd Anjay \
    && git submodule update --init \
    && cmake . \
    && make -j \
    && ./output/bin/demo --server-uri coap://127.0.0.1:5683

Detailed compilation guide

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

git submodule update --init

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 --server-uri coap://127.0.0.1:5683

# uses DTLS in PSK mode, with PSK identity "foo" and secret key "bar" (hex-encoded)
./output/bin/demo --server-uri coaps://127.0.0.1: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://".

Running tests on Ubuntu 16.04:

./devconfig && make check

Running tests on CentOS 7:

# NOTE: clang-3.4 static analyzer (default version for CentOS) gives false
# positives. --without-analysis flag disables static analysis.
./devconfig --without-analysis -DPython_ADDITIONAL_VERSIONS=3.5 && make check

Running tests on macOS Sierra:

# If the scan-build script is located somewhere else, then you need to
# specify a different SCAN_BUILD_BINARY. Below, we are assumming scan-build
# comes from an llvm package, installed via homebrew.
./devconfig -DSCAN_BUILD_BINARY=/usr/local/Cellar/llvm/*/bin/scan-build && make check

License

See LICENSE file.

Commercial support

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

Contributing

Contributions are welcome! See our contributing guide.

eliasweingaertner/Anjay