Skip to content
Snippets Groups Projects

Install, configure and launch

Last edited by guillaume.garzone

Several ways are available to install / build / launch LOM2M:

Once you have launched successfully LOM2M, you can use the provided request collection to test the platform.

Pre-build configuration

LOM2M is structured in order to be malleable at build time. For instance, you can enable or disable some features à pre-build time to reduce the size of the final executable (typically this is useful when you work on an embedded device such as ESP8266). You can find all the possible features to enable/disable in the configuration.h file present in the source code repository (LOM2M/src/server/librairies/lom2m/configuration.h).

N.B.: If some features are disabled in the configration.h file, they are disabled before build. Therefore, these features WILL NOT be compiled nor included in the final executable. If you want to keep the possibility to enable or disable dynamically a feature be sure to let it activated for build time in order for the feature to be included in the executable. (UNIX targets only)

By default, some feature are disabled for ESP targets (to limit the memory and processor occupation). However, they are all enabled by default on UNIX target so they can be managed dynamically through environment variables. (cf. next section)

Here are some examples of what you can configure before building the project: #define PERSISTENCE_FEAT 1 you can set the to 0 to disable the backup feature and work only in memory mode, or let it set to 1 to enable the backup to the filesystem.

#define MQTTS_BINDING 1 you can set this one to 0 to disable the MQTTS feature and all its related code. #define HTTP_BINDING 1 you can do the same for the HTTP feature.

Dynamic configuration and environment variables

Those variables are to be used in a UNIX environment. On ESP target, this feature is not available.

Here are the environment variables you can use to configure dynamically LOM2M:

Dependencies versions

These variables enable to set default version to be used at build time for dependencies. (if not set, default values are used in install-deps.sh script.) In docker, this is used as ARG values that are used only at build time. If you need to use different versions, you can change it in the docker-compose file or use the --build-arg options with the docker build command.

  • ESP8266ARDUINO_VERSION=2.7.4
  • ARDUINO_JSON_VERSION=v6.16.1
  • DALLAS_TEMPERATURE_VERSION=3.9.0
  • FAST_LED_VERSION=3.3.0
  • ONE_WIRE_VERSION=v2.3.5
  • PUB_SUB_CLIENT_VERSION=v2.8
  • NTPCLIENT_VERSION=3.2.0

Local CSE configuration

  • LOM2M_ADMIN_ORIGINATOR=originator
  • LOM2M_LOCAL_POA_IP=public-ip-of-machine-executing-LOM2M
  • LOM2M_LOCAL_POA_PORT=available-port-used-for-LOM2M
  • LOM2M_MAX_NUMBER_OF_INSTANCES_DEFAULT
  • LOM2M_MAX_NUMBER_RESOURCES=20
  • LOM2M_DEFAULT_PROTOCOL=http (use http or mqtts)

Remote CSE configuration:

  • LOM2M_REMOTE_POA=http://ip:port/context
  • LOM2M_REMOTE_CSE_ID=cse-id
  • LOM2M_REMOTE_CSE_NAME=cse-name

Backup feature

  • LOM2M_DATA_PATH="/path/to/backup/file" (This can be set if changing the default backup file location is needed)
  • LOM2M_BACKUP_PERIOD=30000 (Use this to setup a specific backup period (ms))
  • LOM2M_BACKUP_ENABLED=1 (set it to 0 to disable the backup feature)

HTTP binding

  • LOM2M_HTTP_BINDING=1 (set it to 0 to disable the HTTP protocol binding)

MQTTS binding (not included in opensource version)

  • LOM2M_MQTTS_BINDING=0 set it to 1 to enable MQTTS protocol binding. MQTTS binding must be included in the compiled target
  • LOM2M_MQTTS_ENDPOINT="mqtt.broker.endpoint" adress of the MQTTS endpoint
  • LOM2M_MQTTS_PORT=8883
  • LOM2M_MQTTS_RETRY_PERIOD=15000 : MQTTS retry period for the MQTTS client (in ms)
  • LOM2M_MQTTS_TIMEOUT=30000 : configure timeout for MQTT client (ms)
  • LOM2M_MQTTS_CLIENT_ID_PREFIX="example.prefix-" : can be used to setup a specific prefix to be used for the MQTT client identifier

These variables can be saved in a file, or used directly. It is recommended to save the environment variables in a file and to add it in argument of the docker run command.

Launch LOM2M with docker-compose

You can use the provided docker-compose file to test locally LOM2M (by default everything is configured to run locally. You can use this docker-compose as a template to deploy LOM2M). You can find the docker-compose file in lom2m/LOM2M-compose-local-build-LOM2M-only.yml.

To do so, you need to have docker-compose installed in your machine. If not, check this page.

To launch LOM2M and the Eclipse OM2M monitor (useful if you want to test subscriptions and notifications) just be sure to execute this command in the root directory lom2m:

docker-compose -f LOM2M-compose-local-build-LOM2M-only.yml up --build

You can use the -d option to launch the services in detached mode.

To bring the services down use this command:

docker-compose -f LOM2M-compose-local-build-LOM2M-only.yml down

To perform more complex tests you can use the LOM2M-compose-local-build-FULL.yml file to deploy an Eclipse OM2M IN CSE, LOM2M MN CSE, a monitor, and other modules (node-red, oneM2M IoT Dashboard...)

Build LOM2M yourself using docker and the provided Dockerfile

  1. Clone the LOM2M source code repository:

  2. Go to the lom2m directory

  3. From lom2m source code directory, launch the following docker build command:

docker build -t lom2m-tag:test -f docker/LOM2M/Dockerfile .

If you need to use a different version for a dependency, you can use the following:

docker build --build-arg ESP8266ARDUINO_VERSION=x.x.x -t lom2m-tag:test -f docker/LOM2M/Dockerfile .
  1. Once your image is built, you can use it to run a container (cf. previous section, point 2)

Compile LOM2M from source (script)

Build LOM2M on a UNIX system (Linux / MacOS) (LIBC, GIT)

What you need:

  • gcc
  • git
# Clone Arduino ESP8266 git, change the version if needed
git clone --depth=1 --branch 2.7.4 https://github.com/esp8266/Arduino.git

# Set ENV variable used to build LOM2M
export ESP8266ARDUINO=\<path-to-esp8266-arduino-dir\>
# Update submodules used by ESP8266 arduino git
cd $ESP8266ARDUINO
git submodule update --init


# Clone LOM2M src
cd "path/to/lom2m"
git clone <git-repo-url>

# Go to LOM2M src dir
cd "path/to/lom2m"/lom2m/src/server
./install-deps
./clean.sh
./build.sh

# to launch lom2m
cd $ESP8266ARDUINO/tests/host/bin/builtinLed
./builtinLed

Build LOM2M for ESP8266

You can use the provided Dockerfile to have a container all configured to build the target for ESP (cf. docker/LOM2M/Dockerfile-espbuilder). Or you can set up your own environment to do so. Be careful with MacOS systems and Arduino build (32 bits issues if you use Catalina or newer).

The given example is for use on LINUX. If you want to use MacOS, you will need to download the Arduino IDE and point ARDUINO VAR to \\<path-to-Arduino.app\\>/Contents/Java.

What you need:

  • python3
  • JRE
  • gcc
  • git
  • lom2m source code
ARDUINO_IDE_VERSION=2.7.4
ARDUINO=\<path-to-arduino\>/arduino-$ARDUINO_IDE_VERSION
# MAC OS
# ARDUINO=\<path-to-Arduino.app\>/Contents/Java
ESP8266ARDUINO=$ARDUINO/hardware/esp8266com/esp8266
# select sketch to build
sketch=examples/builtinLed/builtinLed.ino
BUILDPATH=\<path-to-build-LOM2M\>/$sketch

mkdir -p $BUILDPATH $BUILDPATH/cache

# LINUX
wget -q -O- https://downloads.arduino.cc/arduino-${ARDUINO_IDE_VERSION}-linux64.tar.xz | tar xJ -C \<path-to-arduino\> ;
# on MacOS go to arduino.cc and download the arduino IDE app

cd $ARDUINO
./install.sh

# cloning ESP8266 materials for build, change version if needed
cd $ARDUINO/hardware/esp8266com
git clone --depth=1 --branch 2.7.4 https://github.com/esp8266/Arduino.git esp8266 
cd  $ARDUINO/hardware/esp8266com/esp8266
git submodule update --init
cd $ARDUINO/hardware/esp8266com/esp8266/tools
python3 get.py

# copying LOM2M sources & installing dependencies
cd \<path-to-lom2m\>/src/server
./install-deps
./clean.sh

# you can build only, flash only or build and flash executable
./espbuildnflash.sh $sketch \<serial-port-dev\>

Test the API

To test the oneM2M API, you can try any oneM2M request in HTTP or MQTTS.

A postman collection is provided in the source code (in lom2m/tests folder). You can import the request collection in Postman client and the environment. The environment provides variables such as IP address, port, etc., to be configured for your specific deployment. By default, the parameters are set to be used locally with the emulator (Unix).

You can change the values as you like to test in a different deployment.

Here is an example using the DISCOVERY request:

Request

GET /mn-DEBA7AB1E042?fu=1 HTTP/1.1
Host: 127.0.0.1:8282
X-M2M-RI: 123
X-M2M-Origin: admin:admin
Accept: application/json

Anwser:

{
    "m2m:uril": [
        "/mn-DEBA7AB1E042/ACP_ADMIN",
        "/mn-DEBA7AB1E042/IPE_led_builtin",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1/messages",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1/operations",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1/messages/uplink",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1/operations/powerON",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1/operations/powerOFF",
        "/mn-DEBA7AB1E042/IPE_led_builtin/LED_1/messages/uplink/4_1611243509515540"
    ]
}

Comments

    Please register or sign in to add a comment.