Adding new objects

The LWM2M model

In LWMM2M, data available on a device is structured as a tree.
The tree is composed of LWM2M nodes (Object/Object Instance/Resource) identified by an identifier (16 bits unsigned-integer).

Device
├── object 0
│   ├── object instance 0
│   │  ├── resource 0
│   │  └── resource 1
│   ├── object instance 1
│   │  ├── resource 0
│   │  └── ...
│   └── ...
└── object 1
    └── ...

Each Object is described by a model. This model should be described in a ddf format defined by OMA (.xml).
The LWM2M secification define a set of objects in the core specification v1.0 (Appendix E.).

0. Security Object
1. Server Object
2. Access Control Object
3. Device Object
4. Connectivity Monitoring Object
5. Firmware Update Object
6. Location Object
7. Connectivity Statistics Object

All the objects defined by the OMA or registered/reserved are available here.

Be careful, some range of Id is reserved and other are "free" to use. see ObjectID Classes.

If all of this is not clear, we strongly recommend to read the LWM2M specification again.

Leshan needs LW2M2M object model

Leshan needs model of objects to work, mainly for encoding/decoding data but not only.

By default :

• Leshan client and server library embed objects model from the core specification (Security, Server, Devices ...), but you could add more.
• Leshan client and server demo embed a lot of models available in the official LWM2M registry.

How to add object support to Leshan ?

Leshan Server Demo

Just download models (xml file) of the objects you want to support here, or create your own models (range 32769-42768).

Put them all in an empty directory, then use the -m object of leshan-server-demo.

-m,--modelsfolder <arg>        A folder which contains object models in OMA DDF(.xml) format.

Leshan Server

Download or create models you need as described above.
Then use the ObjectLoader to load it, it helps to load models from files/folders or resources in your jar/war

// load the core models (Security, Server, Device ...)
List<ObjectModel> models = ObjectLoader.loadDefault();
// load 3 models embedded in a "models" folder of your jar.
String[] modelPaths = new String[] { "31024.xml","10241.xml", "10242.xml"};
models.addAll(ObjectLoader.loadDdfResources("/models/", modelPaths));

// then add it to builder
LeshanServerBuilder builder = new LeshanServerBuilder();
LwM2mModelProvider modelProvider = new StaticModelProvider(models);
builder.setObjectModelProvider(modelProvider);

// then create your server
LeshanServer lwServer = builder.build();
lwServer.start();

Leshan Client

As explained above, you need to get the xml files and load it with ObjectLoaders, but this is not as straight forward as for Leshan Server, you need to implement the object behavior too.

To implements this behavior you should implements the LwM2mObjectEnabler interface. We provide a BaseObjectEnabler abstract class which could be used as base for implementing a new LWM2M object. All of this is very flexible and allow to implement dynamic behavior.

We also provide the ObjectEnabler which is more rigid but also an easier way to define the object behavior. ObjectEnabler is a LwM2mObjectEnabler implementation which delegate the "real" logic to LwM2mInstanceEnabler interface and so you just need to implement this LwM2mInstanceEnabler interface. You don't need to create ObjectEnabler as ObjectsInitializer will do that for you.

// Load model
List<ObjectModel> models = ObjectLoader.loadDefault();
String[] modelPaths = new String[] {"10242.xml"};
models.addAll(ObjectLoader.loadDdfResources("/models", modelPaths));

// Create initializer with your models
ObjectsInitializer initializer = new ObjectsInitializer(new StaticModel(models));
// Create `LwM2mInstanceEnabler` instances.
initializer.setInstancesForObject(LwM2mId.SECURITY, Security.noSec("leshan.eclipseprojects.io", 123));
initializer.setInstancesForObject(LwM2mId.SERVER, new Server(123, 30, BindingMode.U, false));
initializer.setInstancesForObject(LwM2mId.DEVICE, new Device("Manufacturer", "modelNumber", "serialNumber", BindingMode.U.name()));
initializer.setInstancesForObject(10242, new Your10242InstanceEnabler());
// Use it to create LWM2MObjectEnabler
List<LwM2mObjectEnabler> enablers = initializer.createAll();

// Create and start the client
LeshanClientBuilder builder = new LeshanClientBuilder("myendpoint");
builder.setObjects(enablers);
LeshanClient client = builder.build();
client.start();

Look at Leshan client Getting-Started to see how to implement a LwM2mInstanceEnabler.

In all those examples we are using initializer.setInstancesForObject, which will set all the instances available at client start-up. But you should ask yourself how we handle to add a new object instance ? To create new instance, ObjectEnabler need a LwM2mInstanceEnablerFactory. By default ObjectsInitializer will create it for you, it will use the no-arguments constructor of the LwM2mInstanceEnabler. If you need a more complex factory, you can use initializer.setFactoryForObject(objectId, factory). If you want to define a class for an object but not having any instance of this class at startup, just use : initializer.setClassForObject(objectId, clazz)

Leshan Client Demo

By default, leshan-client-demo support a lot of models and you can enable an object just by calling the create command :

  - create <objectId> : to enable a new object.
  - delete <objectId> : to disable a new object.

When you call this command, you should see in the logs :

...  INFO LeshanClientDemo - Object XXXX enabled.

or if the model in not supported by default :

... INFO LeshanClientDemo - Unable to enable Object XXXX : there no model for this.

In this case, just download models (xml file) of the objects you want to support here or create your own one (range 32769-42768), then add it using the -m command line option.

-m <arg>       A folder which contains object models in OMA DDF(.xml)format.

By default leshan-client-demo will create only create "dummy" instance. This is enough to test a server but if you need to implement a real behavior you must modify the leshan-client-demo code.