LwM2M Protocol Gateway

    For more information, see

    LwM2M is built on Constrained Application ProtocolLwM2M gateway - 图2 (opens new window) (CoAP), carried over UDP or SMS, based on REST architecture, so the message structure is simple and compact to worker better in environments where network resources are limited and the device is not always online.

    There are two roles in the LwM2M protocol:

    • LwM2M Server

      LwM2M has two kind services:

      1. LwM2M bootstrap server. The plugin does not implement this server.
      2. LwM2M server. The emqx-lwm2m plugin implement it over UDP/DTLS (but not over TCP/TLS, nor over SMS).

    • LwM2M Client

      An LwM2M client is deployed on an LwM2M device which connects to the server for machine to machine communication.

    Between LwM2M Server and LwM2M Client, the LwM2M protocol defines 4 interfaces.

    1. Bootstrap interface

      This interface is to provide the client with necessary server information (such as server access point) for it to register to the server. The client also makes use of this interface to provide information (such as supported resources) to the server.

    2. Client Registration Interface

      The client registers itself to the server, and the server stores the information about the connection for future use. Communication between client and server is only possible after registration is completed.

    3. Device management and service implementation interface

      Allows the server to access and modify LwM2M client object instances and resources.

    4. Information reporting interface

      Allows the server to subscribe resource information to the client, and the client reports its resource changes to the server in agreed mode.

    LwM2M abstracts the services on the device as Objects and Resources, and defines the attributes and functionalities of various objects in XML files. See for details.

    The LwM2M protocol predefines 8 kinds of objects, namely:

    • Security object
    • Server object
    • Access Control access control object
    • Device object
    • Connectivity Monitoring Connectivity monitoring object
    • Firmware firmware object
    • Location object
    • Connectivity Statistics Connectivity statistics object

    Open , click the Modules tab on the left, and choose to add:

    Select the LwM2M Gateway

    Configure basic parameters:

    image-20200927213049265

    Add a listener:

    Configure listener parameters:

    image-20200927213049265

    Click confirm to enter the configuration parameter page:

    After clicking Add, the module is added: image-20200927213049265

    EMQX-LwM2M is a gateway module of EMQX server, it implements most of the functionalities of LwM2M. MQTT client can access LwM2M-enabled devices through EMQX-LWM2M and devices can also report notification to EMQX-LwM2M for data collection and integration over MQTT protocol.

    With emqx_lwm2m, user is able to send LwM2M commands(READ/WRITE/EXECUTE/…) and get LwM2M response in MQTT way. emqx_lwm2m transforms data between MQTT and LwM2M protocol.

    emqx_lwm2m needs object definitions to parse data from lwm2m devices. Object definitions are declared by organizations in XML format, you could find those XMLs from LwM2MRegistry (opens new window), download and put them into the directory specified by lwm2m.xml_dir. If no associated object definition is found, response from device will be discarded and report an error message in log.

    Register/Update (LwM2M Client Registration Interface)

    • LwM2M Register and Update message will be converted to following MQTT message:

      • Method: PUBLISH
      • Topic: lwm2m/{?EndpointName}/up/resp (configurable, Mountpoint + Register/Update Topic. The same rules apply to other conversion topics)

      • Payload:

        • MsgType register and update:

          • {?EndpointName}: String, the endpoint name of the LwM2M client
          • {?MsgType}: String, could be:
            • “register”: LwM2M Register
            • “update”: LwM2M Update
          • “data” contains the query options and the object-list of the register message
          • The update message is only published if the object-list changed.

    • To send a downlink command to device, publish following MQTT message:

      • Method: PUBLISH
      • Topic: lwm2m/{?EndpointName}/dn

      • Request Payload:

        1. {
        2.     "reqID": {?ReqID},
        3.     "msgType": {?MsgType},
        4.     "data": {?Data}
        5. }
        • {?ReqID}: Integer, request-id, used for matching the response to the request
        • {?MsgType}: String, can be one of the following:
          • “read”: LwM2M Read
          • “discover”: LwM2M Discover
          • “write”: LwM2M Write
          • “write-attr”: LwM2M Write Attributes
          • “execute”: LwM2M Execute
          • “create”: LwM2M Create
          • “delete”: LwM2M Delete

        • {?Data}: Json Object, its value depends on the {?MsgType}:

          • If {?MsgType} = “read” or “discover”:

            1. {
            2.     "path": {?ResourcePath}
            3. }
            • {?ResourcePath}: String, LwM2M full resource path. e.g. “3/0”, “/3/0/0”, “/3/0/6/0”

          • If {?MsgType} = “write” (single write):

            1. {
            2.     "path": {?ResourcePath},
            3.     "type": {?ValueType},
            4.     "value": {?Value}
            5. }
            • {?ValueType}: String, can be: “Time”, “String”, “Integer”, “Float”, “Boolean”, “Opaque”, “Objlnk”
            • {?Value}: Value of the resource, depends on “type”.

          • If {?MsgType} = “write” (batch write):

            1. {
            2.     "basePath": {?BasePath},
            3.     "content": [
            4.         {
            5.             "path": {?ResourcePath},
            6.             "type": {?ValueType},
            7.             "value": {?Value}
            8.     ]
            9. }
            • The full path is concatenation of “basePath” and “path”.
            1. {
            2.     "path": {?ResourcePath},
            3.     "pmin": {?PeriodMin},
            4.     "pmax": {?PeriodMax},
            5.     "gt": {?GreaterThan},
            7.     "st": {?Step}
            8. }
            • {?PeriodMin}: Number, LwM2M Notification Class Attribute - Minimum Period.
            • {?PeriodMax}: Number, LwM2M Notification Class Attribute - Maximum Period.
            • {?GreaterThan}: Number, LwM2M Notification Class Attribute - Greater Than.
            • {?LessThan}: Number, LwM2M Notification Class Attribute - Less Than.
            • {?Step}: Number, LwM2M Notification Class Attribute - Step.

          • If {?MsgType} = “execute”:

            • {?Arguments}: String, LwM2M Execute Arguments.

          • If {?MsgType} = “create”:

            1. {
            2.     "basePath": "/{?ObjectID}",
            3.     "content": [
            4.         {
            5.             "path": {?ResourcePath},
            6.             "type": {?ValueType},
            7.             "value": {?Value}
            8.         }
            9.     ]
            10. }
            • {?ObjectID}: Integer, LwM2M Object ID

          • If {?MsgType} = “delete”:

            1. {
            2.     "path": "{?ObjectID}/{?ObjectInstanceID}"
            3. }
            • {?ObjectInstanceID}: Integer, LwM2M Object Instance ID

    • The response of LwM2M will be converted to following MQTT message:

      • Method: PUBLISH
      • Topic: "lwm2m/{?EndpointName}/up/resp"
      • Response Payload:
      1. {
      2.     "reqID": {?ReqID},
      3.     "imei": {?IMEI},
      4.     "imsi": {?IMSI},
      5.     "msgType": {?MsgType},
      6.     "data": {?Data}
      7. }
      • {?MsgType}: String, can be:
        • “read”: LwM2M Read
        • “discover”: LwM2M Discover
        • “write”: LwM2M Write
        • “write-attr”: LwM2M Write Attributes
        • “execute”: LwM2M Execute
        • “create”: LwM2M Create
        • “delete”: LwM2M Delete
        • “ack”:

      • {?Data}: Json Object, its value depends on {?MsgType}:

        • If {?MsgType} = “write”, “write-attr”, “execute”, “create”, “delete”, or “read”(when response without content):

          1. {
          2.       "code": {?StatusCode},
          3.       "codeMsg": {?CodeMsg},
          4.       "reqPath": {?RequestPath}
          5. }
          • {?StatusCode}: String, LwM2M status code, e.g. “2.01”, “4.00”, etc.
          • {?CodeMsg}: String, LwM2M response message, e.g. “content”, “bad_request”
          • {?RequestPath}: String, the requested “path” or “basePath”

        • If {?MsgType} = “discover”:

          1. {
          2.     "code": {?StatusCode},
          3.     "codeMsg": {?CodeMsg},
          4.     "reqPath": {?RequestPath},
          5.     "content": [
          6.         {?Link},
          7.         ...
          8.     ]
          9. }

        • If {?MsgType} = “read”(when response with content):

          • {?Content}

            1. [
            2.     {
            3.         "path": {?ResourcePath},
            5.     }
            6. ]

        • If {?MsgType} = “ack”, “data” does not exists

    Observe (Information Reporting Interface - Observe/Cancel-Observe)

    • To observe/cancel-observe LwM2M client, send following MQTT PUBLISH:

      • Method: PUBLISH
      • Topic: lwm2m/{?EndpointName}/dn

      • Request Payload:

        1. {
        2.     "reqID": {?ReqID},
        3.     "msgType": {?MsgType},
        4.     "data": {
        5.         "path": {?ResourcePath}
        6.     }
        7. }
        • {?ResourcePath}: String, the LwM2M resource to be observed/cancel-observed.
        • {?MsgType}: String, can be:
          • “observe”: LwM2M Observe
          • “cancel-observe”: LwM2M Cancel Observe
        • {?ReqID}: Integer, request-id, is the {?ReqID} in the request

    • Responses will be converted to following MQTT message:

      • Method: PUBLISH
      • Topic: lwm2m/{?EndpointName}/up/resp

      • Response Payload:

        1. {
        2.     "reqID": {?ReqID},
        3.     "msgType": {?MsgType},
        4.     "data": {
        5.         "code": {?StatusCode},
        6.         "codeMsg": {?CodeMsg},
        7.         "reqPath": {?RequestPath},
        8.         "content": [
        9.             {
        10.                 "path": {?ResourcePath},
        11.                 "value": {?Value}
        12.             }
        13.         ]
        14.     }
        15. }
        • {?MsgType}: String, can be:
          • “observe”: LwM2M Observe
          • “cancel-observe”: LwM2M Cancel Observe
          • “ack”:

    • The notifications from LwM2M clients will be converted to MQTT PUBLISH:

      • Method: PUBLISH
      • Topic: lwm2m/{?EndpiontName}/up/notify

      • Notification Payload:

        1. {
        2.     "reqID": {?ReqID},
        3.     "msgType": {?MsgType},
        4.     "seqNum": {?ObserveSeqNum},
        5.     "data": {
        6.         "code": {?StatusCode},
        7.         "codeMsg": {?CodeMsg},
        8.         "reqPath": {?RequestPath},
        9.         "content": [
        10.             {
        11.                 "path": {?ResourcePath},
        12.                 "value": {?Value}
        13.             }
        14.         ]
        15.     }
        • {?MsgType}: String, must be “notify”
        • {?ObserveSeqNum}: Number, value of “Observe” option in CoAP message
        • “content”: same to the “content” field contains in the response of “read” command

    MQTT and LwM2M conversion

    From the MQTT client, you can send Command to the LwM2M device. The command from MQTT to LwM2M uses the following topic

    1. "lwm2m/{?device_end_point_name}/command".

    The MQTT Payload is a string in json format, which specifies the command to be sent. For more details, please refer to the emqx-lwm2m documentation.

    The reply of the LwM2M device is sent with the following topic

    MQTT Payload is also a string in json format. For more details, please refer to the documentation of emqx-lwm2m.

    WARING

    • “text/plain”
    • “application/octet-stream”
    • “application/vnd.oma.lwm2m+tlv”
    • “application/vnd.oma.lwm2m+json”