Permalink
Fetching contributors…
Cannot retrieve contributors at this time
230 lines (170 sloc) 7.66 KB

Anjay LwM2M library

Build Status Coverity Status

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

  • 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

Ubuntu 16.04 LTS

sudo apt-get install git build-essential cmake libmbedtls-dev
# Optionally for tests:
sudo apt-get install libpython3-dev libssl-dev python3 python3-cryptography python3-jinja2 python3-sphinx clang

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

macOS Sierra with Homebrew

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

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.