Live Objects - complete developer guide

Principle

The DeviceTwin is a Live Objects service that can collect, update and display the device resources information whether the device is connected to Live Objects or not.The device twin is created when the LwM2M device is created in Live Objects.Because the device twin representation is stored by Live Objects, the service can be collect and report device resources and state from apps and other services.

DeviceTwin feature is a way to define, retrieve or interact with a Twin representation of a device.

Device twin features overview.

scale 900*700
skinparam {
  BackgroundColor #EEE
}

skinparam ArrowFontName Arial
skinparam ArrowFontSize 10
skinparam ArrowFontStyle bold
skinparam ArrowFontColor darkred

skinparam component {
  FontSize 13
  FontName Tahoma
  BorderColor lightblue
  BackgroundColor lightyellow
  ArrowFontName Impact
  ArrowColor blue
  ArrowFontColor black
}
skinparam frame {
  BackgroundColor white
}
skinparam folder {
  FontSize 10
}
skinparam rectangle {
  FontSize 10
  BorderColor brown
  BackgroundColor lightyellow
  ArrowFontName Impact
  ArrowColor grey
}

node [LiveObjects] {

  frame "Twin Operations" #LightGrey{
    folder "operations"{
        rectangle "READ /3/0"
        rectangle "WRITE /3/0/1"
    }
  }

  frame "Twin Models"#LightYellow{
    rectangle "/3 Definition"
    rectangle "/1 Definition"
    rectangle "/0 Definition"
  }

  frame  "Twin Devices" #LightBlue{

    folder "Device twin"{
        rectangle "reported"
        rectangle "instantiated"
        rectangle "supported"
    }
  }
  rectangle "reported"{
    rectangle "/3/0/0"
    rectangle "/3/0/9"
  }
  rectangle "instantiated"{
    rectangle "/3/0"
  }
  rectangle "supported"{
    rectangle "/0"
    rectangle "/3"
  }
    [/3 Definition] <|.up. [/3]
    [/0 Definition] <|.up. [/0]
    [LWM2M Device] --down-> [Device twin]
    note on link
        <b><i>supported and instantiated objects,</i></b>
        <b><i>reported values</i></b>
    end note
    [operations] -left->  [LWM2M Device]
    note on link
        <b><i>Operations</i></b>
    end note
  }
}

@enduml

The way to define entities supported and instantiated by a device is called a TwinModel, it’s a list of ObjectsDefinitions where each object includes a list of AttributesDefinitions.

Note: LiveObjects TwinModel is compatible with OMA LWM2M model.

Each twin-capable physical device (LWM2M) connected to LiveObjects has an associated DeviceTwin:

a DeviceTwin is a list of supportedObjects, instantiatedObjects, and reportedValues.
it is possible to send orders (downlink) to a DeviceTwin using commands representation called TwinOperation.

And when a device reports value changes, LiveObjects could produce an associated data message under certain conditions. This condition are handled by a tenant DataRule entry.

Use cases

DeviceTwin use cases are

From Customer API

reads the Twin Model: ObjectDefinitions, and AttributeDefinitions,
reads DeviceTwin supported objects, instantiated objects,
reads DeviceTwin detailed object or detailed object instance with their reported attributes values,
creates,read operation for a given DeviceTwin.
creates,read data rule.

From Device to LiveObjects

a device uses Coap + LwM2M to talk to LiveObjects,
a device reports the supported and instantiated objects,
a device reports the attribute values.
a device respond to a twin operation.