Skip to content

LWMQN Under the Hood

Jump to bottom Edit New page
simen edited this page Feb 20, 2017 · 2 revisions

TBD

Interface LWM2M LWMQN
Bootstrap O Simple auth.
Client Registration
Register O O
Deregister O O
Update O O
Schedule [1] Q mode Schedule
Device Mgmt and Service En.
Read O O
Write O O
Discover O O
Write Attributes O O
Execute O O
Create [2] O X
Delete [2] O X
Ping X O
Announce X O
Information Reporting
Observe [3] O O
Notify [4] O O
Cancel Observation O O

Note:
[1] LWMQN has an interface for clients to checkin and checkout from the network. Once checked out, a client can be powered down (deep sleep) or even powered off.

[2] LWMQN doesn't support Create and Delete to keep things simple, this is for the reasons of security and resource-constrained environment at client-side (machines).

[3] At this moment, LWMQN doesn't support the observation upon an Object. Thus notifying an Object is also not allowed.

[4] LWMQN supports partial update for a notification. Assume you have an Object Instance like { resrc1: 1, resrc2: 2, resrc3: 'hello' }. When LWMQN server receives a notification of this Instance like { resrc3: 'world' }, it will internally be updated to { resrc1: 1, resrc2: 2, resrc3: 'world' }.

2. LWMQN Channels: Topics and Messages

What is LWMQN Channels

LWMQN is equipped with several channels to implement the LWM2M interfaces based on MQTT pub/sub approach. These channels are simply MQTT topics, and such special topics are named as channels to distinguish from generic topics. The LWMQN Client/Server messaging is based on these channels.


Under the Hood

  1. Special Topics for LWMQN Channels
  2. Message through the Channel
  3. Data Type Summary of Messages

1. Special Topics for LWMQN Channels

Channel Client Pub / Server Sub Client Sub / Server Pub
register register/${clientId} register/response/${clientId}
deregister deregister/${clientId} deregister/response/${clientId}
update update/${clientId} update/response/${clientId}
shcedule shcedule/${clientId} shcedule/response/${clientId}
ping ping/${clientId} ping/response/${clientId}
announce - announce
request - request/${clientId}
response response/${clientId} -
notify notify/${clientId} notify/response/${clientId}

************************************************* ### 2. Message through the Channel
Channel Client Pub Server Pub
register { transId, lifetime, ip, mac, version, objList } { transId, status }
deregister { transId } { transId, status }
update { transId, lifetime, ip, version, objList } { transId, status }
shcedule { transId, sleep, duration } { transId, status }
ping { transId } { transId, status }
announce - Any thing can be serialized which depends on implementation
request - { transId, cmdId, oid, iid, rid, data }
response { transId, cmdId, status, data } -
notify { transId, oid, iid, rid, data } { transId, status }

3. Data Type Summary of Messages

Property Data Type Description
transId Number A numeric id for each transaction, e.g., 102
lifetime Number Lifetime of the device. If no message comes from the device within lifetime seconds, the server will deregister this device from the network, e.g., 6000 (secs)
ip String Device ip address, e.g., '192.168.1.60'
mac String Device mac address, e.g., 'd8:fe:e3:e5:9f:3b'
version String LWMQN version, e.g., '0.0.1'
objList Object IPSO Objects and Object Instances live in the client. Each property in objList is an oid: [ iid, ... ] pair, e.g., { 3301: [ 0 ], 3302: [ 6 ], 3303: [ 0, 1, 18 ] }
sleep Boolean To tell server that this client is going to sleep (true) or waking up from sleep (false)
duration Number When a client is going to sleep, it can tell the server of how many seconds from now that this client will check in again
cmdId Number Command id, can be 0(read), 1(write), 2(discover), 3(writeAttrs), 4(execute), 5(observe), 6(notify), and 7(ping)
status Number Status code
oid Number | String Object Id, a numeric id is preferable for IPSO-deifned Object, e.g., 3303 for a temperature sensor. A string id is also accepted if the Object is not an IPSO-defined one
iid Number | String Object Instance Id, a numeric id is preferable but a string is also accepted
rid Number | String Resource Id, a numeric id is preferable for IPSO-deifned Resource, e.g., 5700 for a sensor value. A string is also accepted if the Resource is not an IPSO-defined one
data Depends Payload per request

3. Messaging Examples

Register

  • Client pub a register request
    {
        transId: 12,
        lifetime: 86400,
        ip: '192.168.1.18',
        mac: 'd8:fe:e3:e5:9f:3b',
        version: '0.0.1',
        objList: {
            '3301': [ 0 ],
            '3302': [ 6 ],
            '3303': [ 0, 1, 18 ]
        }
    }
  • Server pub back a register response
{
    transId: 12,
    status: 201     // Created
}

Deregister

  • Client pub a deregister request
{
    transId: 231
}
  • Server pub back a deregister response
{
    transId: 231,
    status: 202     // Deleted
}

Update

  • Client pub an update request
{
    transId: 176,
    lifetime: 86400,            // optional
    ip: '192.168.1.18',         // optional
    version: '0.0.1',           // optional
    objList: {                  // optional
        '3301': [ 0 ],
        '3302': [ 6 ],
        '3303': [ 0, 1, 18 ]
    }
}
  • Server pub back an update response
{
    transId: 176,
    status: 204     // Changed
}

Schedule

  • Client pub a checkin/checkout indication
// (1) Checkin
{
    transId: 88,
    sleep: false
}

// (2) Checkout
{
    transId: 88,
    sleep: true,
    duration: 0
}

// (3) Checkout with a duration
{
    transId: 88,
    sleep: true,
    duration: 600   // will wake up after 600 seconds
}
  • Server pub back a checkin/checkout acknowledgement
// Response for case (1), (2), and (3)
{
    transId: 88,
    status: 200     // OK
}

Ping

  • Client pub a ping request
{
    transId: 241
}
  • Server pub back a ping response
{
    transId: 241,
    status: 200     // OK
}

Announce

  • Client pub: none
  • Server pub an announcement: Any thing can be serialized
'{"foo":"bar","greet":"hello world"}'

Request/Response

  • Server Pub via request channel
{
    transId: 26,
    cmdId: 
    oid:
    iid:
    rid:
    data: 
}
  • Client Pub via response channel
{
    transId: 26,
    cmdId: 
    status: 
    data: 
}

Notify

  • Client pub a notify indication
    • Cannot notify the server of an Object
// (1) Notify an Object Instance
{
    transId: 36,
    oid: 3303,
    iid: 0,
    data: {  // supports partial update, no need to notify with all Resources
        sensorValue: 24,
        units: 'Cel'
    }
}

// (2) Notify a Resource
{
    transId: 36,
    oid: 3303,
    iid: 0,
    rid: 5700,    // sensorValue
    data: 27
}
  • Server pub back a notify acknowledgement
{
    transId: 36,
    status: 204     // Changed
}

4. Device Management Commands

Command Examples

  1. Read
  2. Write
  3. Discover
  4. Write Attributes
  5. Execute
  6. Create (not supported)
  7. Delete (not supported)
  8. Observe
  9. Ping

In the messasge of these requests:

  • Given keys (oid, iid, rid) to alloacte a Resource
  • Given keys (oid, iid) to alloacte an Object Instance
  • Given a key (oid) to allocate an Object

Abbrvs.:

  • REQ: request
  • RSP: response
  • s2c: Direction is from Server to Client
  • c2s: Direction is from Client to Server

Read

  • Command Id: 0 or 'read'
  • REQ (s2c): { transId, cmdId, oid[, iid[, rid]] }
  • RSP (c2s): { transId, cmdId, status, data }
    • Possible status: 205 (Content), 400 (BadRequest), 404 (NotFound), 405 (MethodNotAllowed)
  • Note: none
  • Examples
    • Read an Object 
      // REQ
{
    transId: 10, cmdId: 0, oid: 3303
}

// RSP
{
    transId: 10, cmdId: 0, status: 205,
    data: {
        '0': { sensorValue: 21, units: 'Cel', minMeaValue: 18, maxMeaValue: 23 },
        '1': { sensorValue: 22.6 },
        '2': { sensorValue: 24.1 }
    }
}
    • Read an Object Instance 
      // REQ
{
    transId: 11, cmdId: 0, oid: 3303, iid: 0
}

// RSP
{
    transId: 11, cmdId: 0, status: 205,
    data: { sensorValue: 21, units: 'Cel', minMeaValue: 19, maxMeaValue: 32 }
}
    • Read a Resource 
      // REQ
{
    transId: 12, cmdId: 0, oid: 3303, iid: 0, rid: 5700
}

// RSP
{
    transId: 12, cmdId: 0, status: 205, data: 18
}

Write

  • Command Id: 1 or 'write'
  • REQ (s2c): { transId, cmdId, oid, iid, rid, data }
  • RSP (c2s): { transId, cmdId, status, data }
    • Possible status: 204 (Changed), 400 (BadRequest), 404 (NotFound), 405 (MethodNotAllowed)
  • Note: Writing an Object or Object Instance is in vain, will return status 405 back
  • Examples
    • Write an Object 
      // REQ
{
    transId: 13, cmdId: 1, oid: 3303,
    data: {
        '0': { units: 'F' }
    }
}

// RSP
{
    transId: 13, cmdId: 1, status: 405, data: null
}
    • Write an Object Instance 
      // REQ
{
    transId: 14, cmdId: 1, oid: 3303, iid: 0,
    data: {
        units: 'F'
    }
}

// RSP
{
    transId: 14, cmdId: 1, status: 405, data: null
}
    • Write a Resource 
      // REQ
{
    transId: 15, cmdId: 1, oid: 3303, iid: 0, rid: 5700, data: 22
}

// RSP
{
    transId: 15, cmdId: 1, status: 405, data: '_unwritable_'
}

Discover

  • Command Id: 2 or 'discover'
  • REQ (s2c): { transId, cmdId, oid[, iid[, rid]] }
  • RSP (c2s): { transId, cmdId, status, data }
    • Possible status: 205 (Content), 400 (BadRequest), and 404 (NotFound)
  • Note: Discovering an Object will return you a list of Resource Ids within data.resrcList
  • Examples
    • Discover an Object 
      // REQ
{
    transId: 16, cmdId: 2, oid: 3303
}

// RSP
{
    transId: 16, cmdId: 2, status: 205,
    data: {
        pmin: 1, pmax: 60, cancel: true,
        resrcList: {
            '0': [ 5700, 5701, 5601, 5602, 5603, 5604 ],
            '1': [ 5700 ],
            '2': [ 5700 ]
        }
    }
}
    • Discover an Object Instance 
      // REQ
{
    transId: 17, cmdId: 2, oid: 3303, iid: 0
}

// RSP
{
    transId: 17, cmdId: 2, status: 205,
    data: { pmin: 1, pmax: 60, cancel: true }
}
    • Discover a Resource 
      // REQ
{
    transId: 18, cmdId: 2, oid: 3303, iid: 0, rid: 5700
}

// RSP
{
    transId: 18, cmdId: 2, status: 205,
    data: { pmin: 5, pmax: 10, stp: 3, cancel: true }
}

Write Attributes

  • Command Id: 3 or 'writeAttrs'
  • REQ (s2c): { transId, cmdId, oid[, iid[, rid]], data }
  • RSP (c2s): { transId, cmdId, status, data }
    • Possible status: 204 (Changed), 400 (BadRequest), 404 (NotFound), and 405 (MethodNotAllowed)
  • Note: data is the attributes to be written. LWMQN doesn't support the observation of an Object, thus writting attributes to an Object is in vain, the Client will still return you the current settings.
  • Examples
    • Write attributes to an Object 
      // REQ
{
    transId: 19, cmdId: 3, oid: 3303,
    data: { pmin: 50, pmax: 600 }
}

// RSP
{
    transId: 19, cmdId: 3, status: 204,
    data: { pmin: 1, pmax: 60, cancel: true }   // not changed
}
    • Write attributes to an Object Instance 
      // REQ
{
    transId: 20, cmdId: 3, oid: 3303, iid: 0,
    data: { pmin: 50, pmax: 600 }
}

// RSP
{
    transId: 20, cmdId: 3, status: 204,
    data: { pmin: 50, pmax: 600, cancel: true }
}
    • Write attributes to a Resource 
      // REQ
{
    transId: 21, cmdId: 3, oid: 3303, iid: 0, rid: 5700
    data: { pmin: 50, pmax: 600, stp: 10 }
}

// RSP
{
    transId: 21, cmdId: 3, status: 204,
    data: { pmin: 50, pmax: 600, stp: 10, cancel: true }
}

Execute

  • Command Id: 4 or 'execute'
  • REQ (s2c): { transId, cmdId, oid[, iid[, rid]], data }
  • RSP (c2s): { transId, cmdId, status, data }
    • Possible status: 204 (Changed), 400 (BadRequest), 404 (NotFound), 405 (MethodNotAllowed), 500 (InternalServerError)
  • Note: data, which should be an array, is the arguments apply to the executable Resource. This command only valid for Resources.
  • Examples
    • Execute upon an Object 
      // REQ
{
    transId: 22, cmdId: 4, oid: 3303,
    data: [ 'simen' ]
}

// RSP
{
    transId: 22, cmdId: 4, status: 405, data: null
}
    • Execute upon an Object Instance 
      // REQ
{
    transId: 23, cmdId: 4, oid: 3303, iid: 0,
    data: [ 'simen' ]
}

// RSP
{
    transId: 23, cmdId: 4, status: 405, data: null
}
    • Execute upon an executable Resource 
      // REQ
{
    transId: 24, cmdId: 4, oid: 3303, iid: 0, rid: 'foo'
    data: [ 'simen' ]
}

// RSP
{
    transId: 24, cmdId: 4, status: 204,
    data: 'hello simen: you are executed. XD'
}

Create

  • Not supported

Delete

  • Not supported

Observe

  • Command Id: 5 or 'observe'
  • REQ (s2c): { transId, cmdId, oid, iid, rid, data }
  • RSP (c2s): { transId, cmdId, status, data }
    • Possible status: 205 (Content), 400 (BadRequest), 404 (NotFound), and 405 (MethodNotAllowed)
  • Note: data, aceepts an { option: 1 | 0 } to control the observation. Set data.option to 1 will cancel the reporting. Observation upon an Object is not supported
  • Examples
    • Observe an Object 
      // REQ
{
    transId: 25, cmdId: 5, oid: 3303,
    data: { option: 0 }
}

// RSP
{
    transId: 25, cmdId: 5, status: 405
}
    • Observe an Object Instance 
      // REQ
{
    transId: 26, cmdId: 5, oid: 3303, iid: 0,
    data: { option: 0 }
}

// RSP
{
    transId: 26, cmdId: 5, status: 205
}
    • Observe a Resource 
      // REQ
{
    transId: 24, cmdId: 4, oid: 3303, iid: 0, rid: 5700
    data: { option: 0 }
}

// RSP
{
    transId: 26, cmdId: 5, status: 205
}

Ping

  • Command Id: 7 or 'ping'
  • REQ (s2c): { transId, cmdId }
  • RSP (c2s): { transId, cmdId, status }
    • Possible status: 200 (Changed), 408 (Timeout)
  • Note: none
  • Examples
    • Ping the Client 
      // REQ
{
    transId: 27, cmdId: 7
}

// RSP
{
    transId: 27, cmdId: 7, status: 200
}
Add a custom footer

Home

Overview

Major Classes

MqttShepherd Class

MqttNode Class

Advanced Topics

Appendix

Clone this wiki locally