MQTT protocol

Live Objects supports the MQTT protocol to enable bi-directional (publish/subscribe) communications between devices or applications and the platform.

MQTT must be used with encryption (TLS layer). It is possible to use MQTT without encryption in "device" mode but we strongly recommend a secured connection. MQTT can be used with or without encryption (TLS layer).

Live Objects also supports MQTT over secure WebSocket.

The Live Objects MQTT interface offers multiples "modes":

  • mode "device": dedicated only to device connection use-cases, based on simple JSON messages,

  • mode "connector": dedicated to application that will act as cloud gateway and transfer device status and data from devices toward Live Objects

  • mode "application": useful for your business application to retrieve data or event from Live Objects.

MQTT protocol support

MQTT protocol level supported is 3.1.1 (cf. MQTT Protocol Specification 3.1.1)

Live Objects acts as a standard MQTT message broker with some limitations:

  • the "will" functionality is not implemented, all "willXXX" flags and headers are not taken into account,

  • the "retain" functionality is not implemented,

  • the "duplicate" flag is not used,

  • the "clean session" flag is not used, the server always starts a new session.

Although Live Objects supports all control packets, QoS levels beyond the exchanges are not all fully guaranteed.

QoS definition guaranteed limitation

0

at most once delivery

yes

no

1

at least once delivery

yes

"duplicate" flag is not used,

2

exactly once delivery

no

same as QoS1


Live Objects has several application behaviors depending on the connection mode (username) described in the following section. Currently Live objects supports 3 connection modes:

  • "device" mode used to communicate with a native MQTT device.

  • "external connector" mode is an API that allows communication with devices using other protocols not supported by Live Objects. To communicate with Live Objects, these devices are connected with a backend itself connected in "external connector" mode that can translate requests and responses (from / to) MQTT.

  • "application" mode with this mode, Live Objects provides an application mode to allow business applications to use the MQTT API.

MQTT Connect

The first packet exchanged must be a MQTT CONNECT packet, sent from the client to the MQTT endpoint.

This packet must contain:

  • clientId: usage depends on the "mode", usually the deviceId in "device" mode

  • username: used to select a mode and encoding: (case-sensitive)

  • password: an API Key with the mandatory roles depending on the connection mode

  • willRetain, willQoS, willFlag, willTopic, willMessage: ! Not taken into account !,

On reception, Live Objects validates the API key provided.

  • If the API key is valid, then Live Objects returns a MQTT CONNACK message with return code 0x00 Connection Accepted.

  • If the API key is not valid, then Live Objects returns a MQTT CONNACK message with return code 0x04 Connection Refused: bad username or password, and closes the TCP connection.

MQTT keep alive interval and Ping Req/Res

Live Objects answers to MQTT PINGREQ packets with MQTT PINGRES packets: this is a way for the MQTT client to avoid connection timeouts.

A Keep Alive value of zero (0) has the effect of turning off the keep alive mechanism. This means that, in this case, the Server is not required to disconnect the Client on the grounds of inactivity. Note that a Server is permitted to disconnect a Client that it determines to be inactive or non-responsive at any time, regardless of the Keep Alive value provided by that Client.

MQTT Subscribe

Once connected, the client can at any time subscribe and unsubscribe to/from topics.

Live Objects answers with a MQTT SUBACK packet only once all subscriptions could be resolved:

MQTT specification enforce that a MQTT SUBACK is returned even if actual subscription is impossible / forbidden. In Protocol 3.1 the MQTT client cannot be informed that it subscribed to a non-existing Topic. In Protocol 3.1.1 the MQTT client will receive MQTT SUBACK with corresponding QoS of 0x80 (Failure).

Live Objects answers to MQTT UNSUBSCRIBE packet with a MQTT UNSUBACK packet only once existing subscriptions have been properly closed.

MQTT Disconnect

Live Objects closes the MQTT / TCP connection when receiving a MQTT DISCONNECT message.

TCP Disconnect

When the TCP connection closes (by client or broker), the broker will close the currently active subscriptions, etc.

Endpoints

Type Supported modes Endpoint Description Warnings

MQTT

device

mqtt://mqtt.liveobjects.orange-business.com:1883

Unsecure plain MQTT connection. Not recommended for production grade applications. Only available for prototyping on discover offers. Please reach out to us for specific use cases.

MQTTS

mqtts://mqtt.liveobjects.orange-business.com:8883

Secure MQTTS connection. Recommended for device mode. Supports both server and client authentications.

Secure Websocket

wss://mqtt.liveobjects.orange-business.com:443/mqtt

Secure MQTTS connection over Websocket. Supports server authentication only.

MQTTS

application, connector

mqtts://liveobjects.orange-business.com:8883

Secure MQTTS connection. Recommended. Supports both server and client authentications.

RootCA change in March 2026 see server certificate Root CA section

Secure Websocket

wss://liveobjects.orange-business.com:443/mqtt

Secure MQTTS connection over Websocket. Supports server authentication only.


Live Objects MQTTS endpoints support the following TLS versions:

  • TLS v1.2

  • TLS v1.3

And the following cipher suites:

  • TLS_AES_256_GCM_SHA384 for TLS v1.3 only

  • TLS_AES_128_GCM_SHA256 for TLS v1.3 only

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 for TLS v1.2 only

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Mandatory: For TLS connections, MQTT devices MUST support:

  • At least TLS 1.2

  • Server Name Indication (SNI) extension

TLS Server Name Indication (SNI) extension must be used for TLS connections. The SNI host_name field must match the target domain name. TLS connection is refused if host_name is invalid.

It is strongly recommended to use MQTTS for your production environment.

Deprecated endpoints

The device mode on the following endpoints is deprecated. The End of Service for these mode and enpoint combinations is scheduled for the 16th of March, 2026.

Type Modes Endpoint Description Warnings End of service

MQTT

device

mqtt://liveobjects.orange-business.com:1883

Unsecure plain MQTT connection.

Deprecated

not yet scheduled

MQTTS

mqtts://liveobjects.orange-business.com:8883

Secure MQTTS connection. Supports both server and client authentications.

Deprecated

16th of March, 2026

Websocket

wss://liveobjects.orange-business.com:443/mqtt

Secure plain MQTT connection over Websocket.

Deprecated

16th of March, 2026

MQTTS Server certificates Root CA

The MQTTS server certificates of Live Objects are renewed every year and signed by Digicert.

domain name root certificate

mqtt.liveobjects.orange-business.com

DigiCert Global Root G2

liveobjects.orange-business.com

DigiCert Global Root CA, until 16th of March, 2026, DigiCert Global Root G2 from 16th of March, 2026.

The DigiCert Global Root CA will be distused in April 2026., On Live Objects Servers it will be replaced with DigiCert Global Root G2 in March 2026. The renewal of the truststore must take place before that date

Your device must have in its truststore the root CA DigiCert Global Root G2. Use the Live Objects (firmware) resource update feature to update the truststore.

Your application or external connector must have in its truststore the root CA DigiCert Global Root CA and DigiCert Global Root G2 to ensure smooth transition between the two certification chains.

  • Ensure that you can securely update your device or application software if security vulnerabilities are discovered.

  • Ensure that you have a way to update your root certificate list. Root CA are meant to be long-term certificates but Live Objects might have to change it.

  • Devices must be able to support at least two root CA certificates.

Secure your MQTT connection

Why use Secure MQTT protocol?

Using MQTT with TLS enabled provides privacy and data integrity between your devices/applications and Live Objects. It guarantees that your device/application is communicating with the authentic Live Objects platform, and it prevents a malicious third-party from eavesdropping or tampering. Using secure TLS communication is becoming a de facto standard when communicating over internet as more and more software / operating systems / Hardware refuse to communicate over non-encrypted protocols. Live Objects offers several levels of security that require adapted credentials according to the expected level of security.

MQTT security levels

3 security levels are available, for each one, the authentication is protected by TLS protocol and credentials, the client must have in its truststore and keystore the credentials below :

Authentication\ Credentials

Authentication level

clientId

API_KEY

Root CA certificate

Client certificate

MQTT

basic authentication

☑

☑

☐

☐

MQTTS server authentication

secured authentication

☑

☑

☑

☐

MQTTS server and client authentication

high secured authentication

☑

☑

☑

☑

MQTTS server authentication

A connection to the MQTT server secure endpoints requires that the MQTT clients maintain an up-to-date list of trusted root CA (Certificate Authority) certificates in order to seamlessly handle periodic server certificate updates.

Go further with server and client authentication

Live Objects goes beyond server authentication and implements client authentication based on your own Certification Authority (CA). When enabled for a given API Key, Live Objects will:

  • make sure that only TLS with client authentication is made with this API key when used for MQTT connections

  • make sure that the client certificate has been signed by one of the CA certificates associated to the API key used by the device,

  • verify the identity of the device, by checking that client certificate’s Common Name (CN) matches the device id (in the MQTT client id). This last verification is done for MQTT “device” mode only. (i.e. not for MQTT “application” and “connector” mode)

Live Objects does not provide PKI services, but you can configure your Live Objects account to use your own PKI’s certificates. For the time being, a maximum limit of 10 certificates is set for a tenant.

Client certificat CA issuer requirements

Standard extensions

Basic constraints

A CA issuer certificate (which signed your client certificate) must include the basicConstraints value with the CA field set to TRUE. An end user certificate (device) must either set CA to FALSE or exclude the extension entirely.

You must check key usage extension of your CA issuer certificate, here are some common rules to consider :

Extension KeyUsage defined

In this case the KeyUsage extension must contains the permitted key usage with keyCertSign value. It can only be used to sign end user certificates and not further CAs. The end user certificates are used by the devices.

For example:

basicConstraints=CA:TRUE
keyUsage= keyCertSign <--

Extension KeyUsage not defined

Nothing to do. Your CA issuer can sign your devices certificates.

For example:

basicConstraints=CA:TRUE
without KeyUsage extension <--
Otherwise, in case where this rules are not respected, your CA certificate is rejected by Live Objects.

How to setup client authentication

The client authentication setup is done in 2 steps:

  • Make Live Objects aware of your Certification Authority (CA) by configuring the CA certificate which used to sign the devices certificates.

  • Check that your CA certificate meets standard requirements.

  • Associate that CA certificate with the API key used by your devices/external connector. This will force all communications to Live Objects using MQTT using that API key to be secured with a client certificate (or it will be rejected).

  • Generate a client certificate, signed with your CA certificate, with the MQTT Client ID as common name (CN) (for MQTT "device" mode only).

Client authentication is only available for MQTTS protocol. MQTT over secure websocket connection does not support client authentication.

1. Configure your Certification Authority’s intermediate certificate on Live Objects

Generate a key pair.

 openssl genrsa -out rootCA.key 2048

Use the key pair to generate your CA certificate.

 openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

Configure your certificate on Live Objects:

POST /api/v0/certificates/ca
 {
   "certificate": "your pem formatted certificate",
   "comment": "my awesome intermediate CA certificate"
 }

This call will return an id for your certificate.

Only provision the CA’s intermediate certificate that directly signed the device Certificate Signing Request (CSR). 
 {
  "id": "your_certificate_id"
 }
To get a JSON compliant string of your pem certificate you can use the command line tool jq : cat rootCA.pem | jq -R --slurp

2. Associate this certificate with an Api Key

POST /api/v0/apiKeys/{your-api-key-id}
 {
   "clientCert": {
     "caCertIds": [
       "your-certificate-id1",
       "your-certificate-id2"
     ],
     "required": true
   }
 }
Once a certificate is associated with an Api Key and clientCert.required=true client authenticated MQTTS connection will be mandatory, otherwise the MQTT(s)/websocket connection will be closed with a Bad username or password error.

3. Generate a client certificate for a device with id *your-device-id*

Create a key pair for the device.

 openssl genrsa -out deviceCert.key 2048

Create a certificate signing request from your key pair

 openssl req -new -key deviceCert.key -out deviceCert.csr

Enter the information when prompted

 Country Name (2 letter code) []:
 State or Province Name (full name) []:
 Locality Name (for example, city) []:
 Organization Name (for example, company) []:
 Organizational Unit Name (for example, section) []:
 Common Name (e.g. server FQDN or YOUR name) []: <--------- ENTER YOUR DEVICE URN HERE
 Email Address []:

Generate the device certificate by signing the CSR with your Certification Authority intermediate key.

 openssl x509 -req -in deviceCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out deviceCert.pem -days 365 -sha256

4. Try it

Try your newly configured MQTTS with client configuration by sending a new data on the dev/data topic. We will be using the node mqtt.js client:

mqtt publish -h "mqtt.liveobjects.orange-business.com" --port 8883 -i your-device-id -q 0 -u json+device -C mqtts -t dev/data -m '{"s": "myStreamId", "v": {"temp": 12}}' --key your-cert-private-key --cert your-cert.pem --ca liveObjects.ca.cert.pem -P your-api-key
Once a certificate is associated with an Api Key and clientCert.required=true client authenticated MQTTS connection and MQTTS endpoint usage will be mandatory (see how to use MQTTS).

Debug MQTT/MQTTS connection

Usual error codes returned by MQTT connector when the client try to connect Live Objects over MQTT protocol :

Authentication

Username (depending on your MQTT mode)

API_KEY (password)

Root CA issuer certificate

API key CA certificate

Client certificate (CN=ClientID)

Connack return code

MQTT (basic authentication/TLS)

bad

bad

none

none

none

0x04 bad credentials

MQTT (basic authentication/TLS)

bad

compliant

none

none

none

0x04 bad credentials

MQTT (basic authentication/TLS)

compliant

bad

none

none

none

0x04 bad credentials

MQTT (basic authentication)

compliant

compliant

none

none

none

0x00 accepted

MQTTS server authentication (TLS)

compliant

compliant

Bad, expired or missing

none

none

0x05 not authorized

MQTTS server authentication (TLS)

compliant

compliant

compliant

none

none

0x00 accepted

MQTTS server and client authentication

compliant

compliant

compliant

compliant

none

0x05 not authorized

MQTTS server and client authentication

compliant

compliant

compliant

compliant

CN =/= client ID

0x05 not authorized

MQTTS server and client authentication

compliant

compliant

compliant

compliant

bad certificate chain

0x05 not authorized

MQTTS server and client authentication

compliant

compliant

compliant

compliant

compliant

0x00 accepted

"Device" mode

In Device mode, a single MQTT connection is associated with one specific device.

In Device mode, devices exchange JSON-formatted messages with the Live Objects platform, providing the following capabilities:

  • Device connectivity status reporting

  • Device configuration reporting and updates

  • Resource version reporting and update requests

  • Command reception and response publication

  • Data message publication, storage, and processing in Live Objects

Interactive
Figure 1. Device and data management features

MQTT Connection setup

To establish an MQTT connection in Device mode, use the following credentials:

  • clientId: your device unique identifier (cf. Device Identifier (URN)). It must be between 1 and 128 characters long, containing no spaces or special characters except :, - or _

  • username: json+device (case sensitive)

  • password: a valid API key value with DEVICE_ACCESS role

To find more information regarding Live Objects MQTT endpoints, please refer to: MQTT endpoints

We strongly recommend using a secure connection (MQTTS port 8883).

As soon as the MQTT connection has been accepted by Live Objects, your device will appear as "ONLINE" in Live Objects, with various information regarding the MQTT connection.

Once you close the connection (or if the connection timeouts), your device will appear as "OFFLINE" in Live Objects.

MQTT Client identity (URN)

The "clientId" value, is used as MQTT client Id must be a valid Live Objects URN and conform to the following format:

urn:lo:nsid:{namespace}:{id}

Where:

  • namespace: your device interface identifier "namespace", used to avoid conflicts between various families of identifier (ex: device model, identifier class "imei", msisdn", "mac", etc.).

  • id: your MQTT custom ID (ex: IMEI, serial number, MAC address, etc.)

"namespace" and "id" must only contain alphanumeric characters (a-z, A-Z, 0-9) or : - _ and must avoid # / !.* | +

Examples:

urn:lo:nsid:tempSensor:17872800001W
urn:lo:nsid:gtw_M50:7891001
urn:lo:nsid:gtw-M200:7891:001

Device MQTT topics

Authorized MQTT actions for a device:

Direction Topic Description

Data message publication

publish to

dev/data

to publish a Live Objects JSON data message - JSON compliant with Live Objects specific schema

publish to

dev/v1/data/rawjson/{model}

to publish any JSON message - any JSON with its schema name as {model}

publish to

dev/v1/data/binary

to publish a binary data message and use a decoder associated to the device’s interface

publish to

dev/v1/data/binary/{encoding}

to publish a binary data message and use a decoder directly with the topic’s name

Command management

subscribe to

dev/cmd

to receive commands and announce remote command compatibility

publish to

dev/cmd/res

to return command responses

Configuration management

publish to

dev/cfg

to notify the current configuration or respond to a config update request

subscribe to

dev/cfg/upd

to receive configuration update requests and announce remote configuration update compatibility

Resource management

publish to

dev/rsc

to notify the current resource versions

subscribe to

dev/rsc/upd

to receive resource update requests and announce remote resource update compatibility

publish to

dev/rsc/upd/res

to respond to resource update requests

publish to

dev/rsc/upd/err

to notify resource update error
An AuditLog message will be sent if the device uses an unauthorized topic.

MQTT device provisioning

By default, any device with a valid API Key will be able to connect to Live Objects using MQTT protocol.

You can explicitly define the MQTT capability for a device (see 'Device management - Interfaces' in Swagger documentation).

A device with an interface provisioned as "connector:"mqtt" and "enabled":false will not be able to connect to Live Objects through MQTT protocol.

Data message publication

JSON data publication with Live Objects specific format

To publish JSON data into Live Objects with Live Objects DataMessage schema, your device must publish on the MQTT topic dev/data the following messages:

{
    "streamId": "<<StreamId>>",
    "timestamp": "<<timestamp>>",
    "model": "<<model>>",
    "value": {
       "<<key>>":"<<value>>"      // a free JSON object
    },
    "location": {
       "lat":<<>>,
       "lon":<<>>,
       "alt":<<>>,
       "accuracy":<<>>,
       "provider":<<>>
    },
    "tags": [<<tag1>>,<<tag2>>,...]
}

By using the MQTT topic dev/data with the Live Objects JSON DataMessage schema, you can provide specific information such as the measurement timestamp of your data. Data published by devices through MQTT will be processed by the Data enrichment logic.

Message fields:

  • streamId : (optional) identifier of the timeseries this message belongs to,

  • timestamp : (optional) date/time associated with the message, is ISO 8601 format,

  • model : (optional) a string identifying the schema used for the "value" part of the message, to avoid conflict at data indexing,

  • value : (mandatory) a free JSON object describing the collected information,

  • tags : (optional) list of strings associated to the message used to carry extra-information,

  • lat, lon : (optional) latitude, longitude details of the geo location associated with the message (in degrees),

  • alt : (optional) height from sea level (in meters),

  • accuracy : (optional) the value depends on the combination of the tools provided the geo location tools (provider),

  • provider : (optional) GPS, cellular or custom

If not provided and not set via the device definition, the "streamId" will be urn:lo:nsid:mqtt:{clientId}.
If not provided, the "timestamp" will be the publication timestamp.

Please read this chapter to have the complete dataMessage description.

Example:

{
    "streamId": "mydeviceTemp1234",
    "timestamp": "2020-10-13T12:15:02Z",
    "model": "tempV2",
    "value": {
        "temp": 12.75,
        "humidity": 62.1,
        "doorOpen": true
    },
    "location": {
        "lat": 48.86667,
        "lon": 2.33333,
        "alt": 35.2,
        "accuracy": 12.3,
        "provider": "GPS"
    },
    "tags": [ "CityNYC", "Prototype" ]
}

JSON data publication with any JSON payload

To publish any JSON data into Live Objects, your device must publish on the MQTT topic dev/v1/data/rawjson/{model}.
A Live Objects DataMessage will be generated using the provided information.
The "streamId" will be urn:lo:nsid:mqtt:{clientId}, if not set in the device definition
The "timestamp" will be the publication timestamp.
The mandatory "model" will be the model specified with the publication topic, for example "version1".

Example:

publish dev/v1/data/rawjson/version1 with MQTT Payload

{
   "temp": 12.75,
   "humidity": 62.1,
   "doorOpen": true
}

will generate the Live Objects dataMessage :

{
    "streamId": "urn:lo:nsid:mqtt:\{clientId\}",
    "timestamp": "2020-10-13T12:15:02Z",
    "model": "version1",
    "value": {
        "temp": 12.75,
        "humidity": 62.1,
        "doorOpen": true
    }
}

if you want to change the JSON schema of the payload, use another model to avoid indexing conflicts

Example:

publish dev/v1/data/rawjson/version2 with MQTT Payload

{
   "temp": 20.0,
   "humidity": 68.8,
   "doorOpen": {
      "status" : true,
      "since" : "2019-10-12T12:15:02Z"
   }
}

will generate the Live Objects dataMessage :

{
    "streamId": "urn:lo:nsid:mqtt:\{clientId\}",
    "timestamp": "2020-10-13T12:15:02Z",
    "model": "version2",
    "value": {
               "temp": 20.0,
               "humidity": 68.8,
               "doorOpen": {
                  "status" : true,
                  "since" : "2019-10-12T12:15:02Z"
                           }
               }
}

Binary/hexa data publication

There are two different ways to publish binary data in Live Objects:

Topic Description

dev/v1/data/binary

Useful if you pre-provisioned your device using http API or the web portal. You can specify the "encoding" when the interface is created in the device inventory and use the decoding service. (1)

dev/v1/data/binary/{encoding}

This topic allows to specify directly the "encoding" that is used to match with a decoder name provisioned in Live Objects. With this topic, you don’t have to declare the "encoding" in the device inventory.
In both ways, the "encoding" value must match with the "name" of the decoder you want to use to decode the payload.

(1) The workflow if you prefer to declare the encoding in the device inventory is:

  • Create or update the device’s interface in the device inventory using http API or the web portal. See more information here.

  • Publish to the topic dev/v1/data/binary

In both cases, when pushing binary data, a dataMessage will be generated with the following values:

  • streamId: device urn

  • timestamp: timestamp of MQTT publication

  • value.payload: binary content of MQTT publication as a string in hexBinary http://www.datypic.com/sc/xsd/t-xsd_hexBinary.html

  • model: if a model is set in the decoder then it will be added. if not, this field is empty

When you publish binary data into Live Objects, only binary or javascript encoders (public or private) can be invoked. The csv decoder would not work in this case.

Please refer to the decoding service section for decoders management.

Examples:

Using the topic dev/v1/data/binary/{encoding}

  • Considering the following binary decoder already provisioned in Live Objects:

{
    "encoding": "my_encoding_v0",
    "format": "float sent_value;",
    "enabled": true,
    "model":"my_encoding_model_v0"
}

  • Sending a MQTT message with following bytes 0x41200000 as a payload on topic dev/v1/data/binary/my_encoding_v0, it will generate and store the following message:

{
    "timestamp" : "2020-10-31T16:15:21.288Z,"
    "streamId" : "urn:lo:nsid:mqtt:123456,"
    "value": {
        "payload": "41200000",
        "sent_value": 10.0
    },
    "model": "my_encoding_model_v0"
}

Using the topic dev/v1/data/binary

  • Declaration of the encoding in the device’s interface using http API: PATCH /api/v1/deviceMgt/devices/{deviceId}/interfaces/{interfaceId}

{
  "connector": "mqtt",
  "nodeId": "123456",
  "enabled": true,
  "status": "ONLINE",
  "definition": {
    "encoding": "my_encoding_v0",        // the name of the decoder that will be used to decode the payload
    "clientId": "123456"
  }
}

Considering the same decoder than in the previous example.

  • Sending a MQTT message with following bytes 0x41200000 as a payload on topic dev/v1/data/binary, it will generate and store the following message:

{
    "timestamp" : "2020-10-31T16:15:21.288Z,"
    "streamId" : "urn:lo:nsid:mqtt:123456,"
    "value": {
        "payload": "41200000",
        "sent_value": 10.0
    },
    "model": "my_encoding_model_v0"
}

Configuration

Current Configuration

To notify Live Objects of its current configuration, your device must publish a message to the MQTT topic dev/cfg with the following JSON structure:

{
   "cfg": {
      "<<param1Key>>": {
         "t": "<<param1Type>>",
         "v": <<param1Value>>
      },
      ...
   }
}

Message fields:

  • param{X}Key: the identifier for the device configuration parameters,

  • param{X}Type : indicates the config parameter type between

    • "i32": the value must be an integer from -2,147,483,648 to 2,147,483,647,

    • "u32": the value must a positive integer from 0 to 4,294,967,295,

    • "str": the value is a UTF-8 string,

    • "bin": the value is a base64 encoded binary content,

    • "f64": the value is float (64 bits) value,

  • param{X}Value : the config parameter value.

Example:

{
   "cfg": {
      "log_level": {
         "t": "str",
         "v": "DEBUG"
      },
      "secret_key": {
         "t": "bin",
         "v": "Nzg3ODY4Ng=="
      },
      "conn_freq": {
         "t": "i32",
         "v": 80000
      }
   }
}

Update Configuration

When your device is ready to receive configuration updates, it can subscribe to the MQTT topic dev/cfg/upd from where it will receive messages of the following format:

{
   "cfg": {
      "<<param1Key>>": {
         "t": "<<param1Type>>",
         "v": <<param1Value>>
      },
      ...
   },
   "cid": <<correlationId>>
}

Message fields:

  • param{X}Key : The identifier of a device configuration parameter that must be updated,

  • param{X}Type, param{X}Value : the new type and value to apply to the parameter,

  • correlationId : an identifier that your device must set when publishing your new configuration, so that Live Objects updates the status of your configuration parameters.

Example:

{
   "cfg": {
      "logLevel": {
         "t": "bin",
         "v": "DEBUG"
      },
      "connPeriod": {
         "t": "i32",
         "v": 80000
      }
   },
   "cid": 907237823
}

Response publication

Once your device has processed a configuration update request, it must return a response to Live Objects by publishing on topic dev/cfg the current value for the parameters that were updated:

{
   "cfg": {
      "<<param1Key>>": {
         "t": "<<param1Type>>",
         "v": <<param1Value>>,
      },
      ...
   },
   "cid": <<correlationId>>
}

Message fields:

  • config : the new configuration of your device (complete or at least all parameters that were in the configuration update request),

  • correlationId : the correlationId of the configuration update request.

Example:

{
   "cfg": {
      "logLevel": {
         "t": "bin",
         "v": "DEBUG"
      },
      "connPeriod": {
         "t": "i32",
         "v": 80000
      }
   },
   "cid": 907237823
}

If the new value for a parameter is the one that was requested in the configuration update request, the parameter will be considered as successfully updated by Live Objects.

If the new value for a parameter is not the one request, the parameter update will be considered as "failed" by Live Objects.

Commands

Retrieve the command request

When your device is ready to receive commands, it can subscribe to the MQTT topic dev/cmd from where it can receive the following messages:

{
   "req":  "<<request>>",
   "arg": {
      "<<arg1>>": <<arg1Value>>,
      "<<arg2>>": <<arg2Value>>,
      ...
   },
   "cid":  <<correlationId>>
}

Message fields:

  • request : string identifying the method called on the device,

  • arg{X}, arg{X}Value : name and value (any valid JSON value) of an argument passed to the request call,

  • correlationId : an identifier that must be returned in the command response to help Live Objects match the response and request.

Example:

{
   "req":  "buzz",
   "arg": {
      "durationSec": 100,
      "freqHz":     800.0
   },
   "cid": 12238987
}

Response publication

To respond to a command, your device must publish the response to the MQTT topic dev/cmd/res with a message of the following format:

{
   "res": {
      "<<res1>>": "<<res1Value>>",
      "<<res2>>": "<<res2Value>>",
      ...
   },
   "cid":  <<correlationId>>
}

Message fields:

  • res{X}, res{X}Value : optional information returned by the command execution,

  • correlationId : a copy of the command correlationId value.

Example #1:

{
   "res": {
      "done": true
   },
   "cid": 12238987
}

Example #2:

{
   "res": {
      "error": "unknown method 'buzz'"
   },
   "cid": 12238987
}

Any response of the device will set the command state to PROCESSED and the optional information will be available in the command result.

Resources management

Current Resources publication

Once connected, your device can announce the currently deployed versions of its resources by publishing a message on MQTT topic dev/rsc with the following format:

{
   "rsc": {
      "<<resource1Id>>": {
         "v": "<<resource1Version>>",
         "m": <<resource1Metadata>>
      },
      "<<resource2Id>>": {
         "v": "<<resource2Version>>",
         "m": <<resource2Metadata>>
      },
      ...
   }
}

Message fields:

  • resource{X}Id : resource identifier,

  • resource{X}Version : currently deployed version of this resource,

  • resource{X}Metadata : (JSON object) (optional) metadata associated with this resource, useful to resource update.

Example:

{
   "rsc": {
      "X11_firmware": {
         "v": "1.2",
         "m": {
            "size": <<firmware size in mbytes>>,
            "md5": "<<firmware sign>>",
         }
      },
      "X11_modem_driver": {
         "v": "4.0.M2"
      }
   }
}

Resources update

When your device is ready to receive resource update request, it just needs to subscribe to MQTT topic dev/rsc/upd. Then, the device will receive the request as a message in the following JSON format:

{
   "id": "<<resourceId>>",
   "old": "<<resourceCurrentVersion>>",
   "new": "<<resourceNewVersion>>",
   "m": {
      "size": <<firmware size in mbytes>>,
      "md5": "<<firmware sign>>",
   },
   "cid": "<<correlationId>>"
}

Message fields:

  • resourceId : identifier of resource to update,

  • resourceCurrentVersion : current resource version,

  • resourceNewVersion : new resource version, for new firmware downloading,

  • correlationId : an identifier that must be returned in the resource update response to help Live Objects match the response and request.

Example:

{
   "id": "X11_firmware",
   "old": "1.1",
   "new": "1.2",
   "m": {
      "uri": "http://.../firmware/1.2.bin",
      "md5": "098f6bcd4621d373cade4e832627b4f6"
   },
   "cid": 3378454
}

Response publication

Once your device receives a "Resource update request", it needs to respond to indicate if it accepts or not the new resource version, by publishing a message on topic dev/rsc/upd/res with the following JSON format:

{
   "res": "<<responseStatus>>",
   "cid": "<<correlationId>>"
}

Message fields:

  • responseStatus : indicates the response status to the resource update request:

    • "OK" : the update is accepted and will start,

    • "UNKNOWN_RESOURCE" : the update is refused, because the resource (identifier) is unsupported by the device,

    • "WRONG_SOURCE_VERSION" : the device is no longer in the "current" (old) resource version specified in the resource update request,

    • "WRONG_TARGET_VERSION" : the device doesn’t support the "target" (new) resource version specified in the resource update request,

    • "INVALID_RESOURCE" : the requested new resource version has incorrect version format or metadata,

    • "NOT_AUTHORIZED" : the device refuses to update the targeted resource (ex: bad timing, "read-only" resource, etc.),

    • "INTERNAL_ERROR" : an error occurred on the device, preventing for the requested resource update,

  • correlationId : copy of the correlationId field from the resource update request.

Example #1:

{
   "res": "OK",
   "cid": 3378454
}

Example #2:

{
   "res": "UNKNOWN_RESOURCE",
   "cid": 778794
}

Response error

Device can report a custom resource update error by publishing a message on MQTT topic dev/rsc/upd/err with the following format:

{
   "errorCode":"ERROR_CODE",
   "errorDetails":"error details"
}

Message fields:

  • errorCode : (optional) device error code,

  • errorDetails : device error details

These fields are limited to 256 characters. Characters outside of this limit will be ignored.

Example:

{
   "errorCode":"DEV123.Z_FIRMW_CRC",
   "errorDetails":"error while loading firmware, bad CRC"
}

"External connector" mode

Connection

When initiating the MQTT connection, to select the "connector" mode you must use the following credentials:

  • clientId: any string between 1 and 128 characters long, containing no spaces or special characters except :, - or _ . The MQTT protocol indicates it must be unique per connection, but Live Objects does not enforce it.

  • username: connector (case sensitive)

  • password: a valid API Key with CONNECTOR_ACCESS role

To find more information regarding Live Objects MQTT endpoints, please refer to: MQTT endpoints

You must use a secured connection (MQTTS port 8883). The MQTT non-secured connection is not supported for "external connector" mode.

Summary

In "connector" mode, you can manage following device actions:

  • NodeStatus: publish in Live Objects a NodeStatus to set the ONLINE/OFFLINE status of the device (i.e. the node) and its capabilities

  • DataMessage: publish in Live Objects a DataMessage sent by the device

  • Command: subscribe to command requests and publish command responses

  • Configuration: handle configuration request or report modifications of a configuration of a device

  • Resource: manage resource update request or report current resource of a device behind the external connector

Direction Topic Description

NodeStatus publication

Publish

connector/v1/nodes/{nodeId}/status

To publish a NodeStatus for a device

Data message publication

Publish

connector/v1/nodes/{nodeId}/data

To publish a device DataMessage (telemetry event) to Live Objects

Commands

Subscribe

connector/v1/requests/command

To subscribe to command requests for devices. Commands can be manage through HTTP APIs.

Publish

connector/v1/responses/command

To publish a device command response

Configurations

Publish

connector/v1/current/configuration

To send a report of an initial configuration of a device to Live Objects

Subscribe

connector/v1/requests/configuration

To be notified (from Live Objects) of a configuration update for a device

Publish

connector/v1/responses/configuration

To respond/acknoledge to a device configuration request

Resources

Publish

connector/v1/current/resource

To send a report of resources current versions (firmware versions) of a device to Live Objects

Subscribe

connector/v1/requests/resource

To be notified (from Live Objects) of a resource version ugrade request

Publish

connector/v1/responses/resource

To respond/acknoledge to a resource version update request

NodeStatus publication

A NodeStatus publication allows to set the ONLINE/OFFLINE status of the device and its capacity to receive or not command requests.

The topic to publish is: connector/v1/nodes/{nodeid}/status

If the nodeId in the publication topic is unknown by Live Objects, a device with this NodeStatus information will be auto-provisioned in the Device inventory.

If the nodeId is already declared for a device in the Device inventory, then this NodeStatus information will update the corresponding device state in the Device inventory.

The link between a DeviceId and a NodeId is described in the Device and connectivity chapter.

The payload of this publication should follow :

NodeStatus publication
{
    "status": "ONLINE",
    "capabilities": {
        "command": {
            "available": true
        },
        "configuration": {
            "available": true
        },
        "resource": {
            "available": true
        }
    },
    "lastContact": "2019-05-20T16:01:47Z",
    "sessionSequenceId": 1,
    "eventSequenceId": 3
}

Only the 'status' field is mandatory.

Field Description

status

(Mandatory). Either 'ONLINE' or 'OFFLINE'.

capabilities.command

(Optional). Define if the device is able to receive commands. If true, you will be able to send commands to this device using the HTTP API.

capabilities.configuration

(Optional). Define if the device is able to receive configuration update. If true, you will be able to send new configurations to this device using the HTTP API.

capabilities.resource

(Optional). Define if the device is able to receive resource update. If true, you will be able to send new resource update to this device using the HTTP API.

lastContact

(Optional). Should follow ISO-8601 format. Set the lastContact information that will be updated in DataManager.

sessionSequenceId

(Optional). If present, the event will be taken into account only if no previous event had a higher sessionSequenceId.

eventSequenceId

(Optional). If present, the event will be taken into account only if no previous event had a higher sessionSequenceId or eventSequenceId.

As messages are asynchronously handled by Live Objects, sessionSequenceId and eventSequenceId mechanism allows to enforce message ordering (only the last status message will be taken into account). If this ordering is mandatory for your application, you should set them. For a unique MQTT session, sessionSequenceId should remain identical; and you can use epoch milliseconds from your application server as eventSequenceId.

If the publication succeeds, Live Objects will acknowledge the message according to the QoS level.

If the publication fails (for ex. because the JSON is badly formatted), Live Objects will nevertheless acknowledge the message according to the QoS level, and an AuditLog message will be sent with failure details.

Messages publication as a device

A DataMessage publication in the "connector" mode allows to send a DataMessage on behalf of a specific device.

The topic to publish is: connector/v1/nodes/{nodeid}/data

The payload of this publication should follow :

DataMessage publication
{
    "streamId": "urn:lo:nsid:detector_A8:12435355",
    "timestamp": "2019-05-20T16:01:47Z",
    "model": "data_v0",
    "value": {
        "temperature" : 14.6,
		"battery" : 53,
		"messageAlert":"low battery"
    },
    "location": {
        "lat": 48.86667,
        "lon": 2.33333,
        "alt": 35.2,
        "accuracy": 12.3,
        "provider": "GPS"
    },
    "tags": [ "production", "london" ]
}
Field Description

streamId

(Optional). The streamId where the data will be stored in; and retrieved using the HTTP store API. If not set, the default streamId set for this device in the Device inventory will be used. Should not contain any of the following character : ' " \ ; { } ( )

timestamp

(Optional). Should follow ISO-8601 format. If not set, current timestamp will be used.

model

(Optional). Can not contains ' ' (space) or '.' (dot) character. Model is needed to be able to use the search APIs on fields inside the value object.

value

(Optional). JSON compliant object. No inner field name should contains '.' (dot) character.

location

(Optional). If set, geo-query will be available through search APIs.

tags

(Optional) List of additional information used to tag the DataMessage

If the publication succeeds, Live Objects will acknowledge the message according to the QoS level.

If the publication fails (for ex. because the JSON is badly formatted), Live Objects will nevertheless acknowledge the message according to the QoS level, and an AuditLog message will be sent with anomaly details.

Encoded DataMessage publication

In order to use the decoding capability of Live Objects, a DataMessage must contains additional 'value.payload' and 'metadata.encoding' fields :

Encoded DataMessage publication
{
    "value": {
        "payload": "000003F5000000DD"
    },
    "metadata": {
        "encoding": "twointegers"
    }
}
Field Description

value.payload

(Mandatory). Payload to decode. In case of binary content, HexBinary String representation of the payload to decode.

metadata.encoding

(Mandatory). Encoded format name, that should match the 'encoding' name of the decoder that can process this message.

All other fields of DataMessage (streamId, timestamp, location, tags…​) can also optionally be set in the encoded DataMessage.

An alternative is to set the encoding property in the x-connector device’s interface definition through DeviceManagement APIs.

Commands

You can refer to commands description to have insights on the devices commands workflow. Using external connector mode, the basics are:

  • once connected in external connector mode, subscribe to command requests

  • create a command targeting a specific device using HTTP APIs or the web portal

  • when this device is connected (publishing a NodeStatus message with a command capability set to true), this command request is published into subscribed topic connector/v1/requests/command

  • optionally, publish the device command response

  • the command status is updated, and can be retrieved using HTTP APIs.

Retrieve the command request

Your external connector will receive all command requests targeting your devices.

This command requests are created through Live Objects HTTP APIs; please see dedicated section to know more about command requests.

The topic to subscribe is: connector/v1/requests/command

The received message in the subscribed topic has this model:

Command request message
{
    "id": "0f1253df-9b34-4e97-8e1e-457317107271",
    "nodeId": "myDevice",
    "value": {
        "req": "on",
        "args": {
            "level": 75
        }
    },
    "ackMode": "APPLICATIVE"
}
Field Description

id

(Mandatory). Unique id of the command request. The command response will use this id to correlate request and response.

nodeId

(Mandatory). Define the request’s targeted nodeId.

value

(Optional). The command request value that have been set when created through the HTTP API (any JSON Object).

ackMode

(Mandatory). The acknowledgement mode of this command (set when the command is created through the HTTP API). Either NONE, NETWORK or APPLICATIVE.

If ackMode is NETWORK or APPLICATIVE, a command response with the request’s id should be published as described command response section in order to update the command’s status. In this MQTT 'connector' mode, NETWORK and APPLICATIVE ackModes lead to the same behaviour.

Response publication

In order to reply to a command request, your external connector should publish to the topic: connector/v1/responses/command.

Command response message
{
    "id": "0f1253df-9b34-4e97-8e1e-457317107271",
    "nodeId": "myDevice",
    "response": {
        "status": "ok",
        "message": {
            "level": 75
        }
    }
}
Field Description

id

(Mandatory). id of the command request that triggered this response.

nodeId

(Mandatory). the nodeId which has generated the response (should be the same as the one in the request).

response

(Optional). This JSON Object will be stored as the command response when retrieved through he HTTP API.

With this response, the command’s status will change to PROCESSED. And if there is other command requests in queue for this device, the next one will be published.

If the publication succeeds, Live Objects will acknowledge the message according to the QoS level.

If the publication fails (for ex. because the JSON is badly formatted), Live Objects will nevertheless acknowledge the message according to the QoS level, and an AuditLog message will be sent with failure details.

Configurations

You can refer to configuration description to have insights on the devices configuration workflow.

Using external connector mode, the basics regarding this feature are:

  • connect to Live Objects MQTT in external connector mode, subscribe to configuration requests on the following topic connector/v1/requests/configuration

  • connect the device (publish a NodeStatus message with a configuration capability set to true),

  • set requested configuration targeting a specific device behind your external connector using HTTP APIs or the web portal

  • a configuration request will be received on the topic you suscribed above

  • when configuration is set on the device, your external connector publishes a device configuration response to connector/v1/responses/configuration

  • the configurations are updated, and can be retrieved using HTTP APIs: liveobjects.orange-business.com/api/v1/deviceMgt/devices/{deviceId}/config

Also, a device can change its configuration by itself. To report a configuration change, your external connector must publish in connector/v1/current/configuration

Retrieve the configuration request

Your external connector will receive all configuration requests targeting your devices.

These configuration requests are created through Live Objects HTTP APIs or web portal. Please see dedicated section to know more about configuration requests.

The topic to subscribe is: connector/v1/requests/configuration

The received message on the subscribed topic has this model:

Configuration request message
{
	"nodeId": "9ea64eb7-a5b4-4573-86e3-b6d949dc55a3",
	"targetVersion": 363745365,
	"parameters": {
		"my_param1": {
			"type": "UINT32",
			"value": 8035095625792325998
		},
		"my_param2": {
			"type": "FLOAT",
			"value": 0.8862329945028716
		},
		"my_param3": {
			"type": "BINARY",
			"value": "WldGbE16QXdtRmlPV1pt"
		},
		"my_param4": {
			"type": "INT32",
			"value": 1101263487
		},
		"my_param5": {
			"type": "STRING",
			"value": "my config as a string"
		}
	}
}
Field Description

nodeId

(Mandatory). Define the request’s targeted nodeId.

targetVersion

(Mandatory). The configuration request version for all provided parameters

parameters

(Mandatory). A JSON object where each field is a parameter name and each value a ParameterValue object. This format is the same that is used by the HTTP APIs. See the our swagger.

Response publication

In order to reply to a configuration request, your external connector must publish in the topic: connector/v1/responses/configuration.

configuration request and configuration response have the same format. To acknowledge a configuration request on a specific parameter, the response must contain the same target version and value.

Configuration response message
{
	"nodeId": "9ea64eb7-a5b4-4573-86e3-b6d949dc55a3",
	"targetVersion": 363745365,
	"parameters": {
		"my_param1": {
			"type": "UINT32",
			"value": 8035095625792325998
		},
                "my_param2": {
			"type": "FLOAT",
			"value": 0.8862329945028716
		}
	}
}

With this response, "my_param1" and "my_param2" are acknowledged. It can be checked on the portal or with HTTP APIs.

If the publication succeeds, Live Objects will acknowledge the message according to the QoS level.

If the publication fails (for ex. because the JSON is badly formatted), Live Objects will nevertheless acknowledge the message according to the QoS level, and an AuditLog message will be sent with failure details.

Publish the current device configuration in Live Objects

In addition to these two topics described in the previous chapter, Live Objects allows your external connector to announce current configuration of a device.

The topic to publish is: connector/v1/current/configuration

The message format is the same than before, except that there is no targetVersion.

Current configuration message
{
	"nodeId": "9ea64eb7-a5b4-4573-86e3-b6d949dc55a3",
	"parameters": {
		"my_param4": {
			"type": "INT32",
			"value": 123
		},
                "my_param5": {
			"type": "FLOAT",
			"value": 0.45562329946543
		}
	}
}

Resources

You can refer to resource description to have more information on the device resources management workflow.

Using external connector mode, the basics regarding this feature are:

  • Connect to Live Objects using MQTTS in external connector mode

  • Connect the device (publish a NodeStatus message with a resource capability set to true)

  • Send to Live Objects the current version of each device resource by publishing on connector/v1/current/resource

  • Subscribe to resources update requests with the following topic connector/v1/requests/resource

  • In order to update a resource for a given device, set its target version with HTTP APIs or the web portal

  • A resource update request will be received on the topic you suscribed above

  • Download the resource with the given resource url

  • Update your device with the resource (firmware)

  • (opt) Inform Live Objects of failure of the update process. Publish a device resource update response to connector/v1/responses/resource

  • When your resource is updated, send to Live Objects the new version of each device resource. publish on connector/v1/current/resource

  • The resource update informations can be retrieved using HTTP APIs: liveobjects.orange-business.com/api/v1/deviceMgt/devices/{deviceId}/resources/updates

Be notified of the resources update request

Your external connector will receive all resources update requests targeting your devices.

These resources update requests are created through Live Objects HTTP APIs or web portal. Please see dedicated section to know more about resource update.

The topic to subscribe is: connector/v1/requests/resource

The received message on the subscribed topic has this model:

resource update request message
{
	"nodeId": "CfnpFC6r",
	"resourceId": "my_resource",
	"updateCorrelationId": "5fc0db74e4332f0001aadf0c",
	"sourceVersion": "1.0",
	"targetVersion": "2.0",
	"delivery": {
		"type": "HTTP_DELIVERY",
		"uri": "https://liveobjects.orange-business.com:443/dl/r7n2b87cc6t8l6pst2t7avg1h5",
		"md5": "6dcdc9dcef09d8571994ac1b712b34c0",
		"size": 1024
	}
}
Field Description

nodeId

(Mandatory). Define the request’s targeted nodeId.

resourceId

(Mandatory). The resource id

updateCorrelationId

(Mandatory). The correlation id for this specific resource update

sourceVersion

(Mandatory). The current version of the resource

targetVersion

(Mandatory). The target version for the resource

delivery

Informations needed for resource download

delivery.type

should be HTTP_DELIVERY

delivery.uri

Download URI

delivery.md5

signature (md5) of the raw (non Base64-encoded) resource file

delivery.size

file size in bytes

Resource update report publication

In order to send a report to Live Objects on the resource update process, your external connector must publish on the topic: connector/v1/responses/resource.

The response is optional but is useful when an error occurs during the update process in the device side. If the update succeeded in the device side, your external connector must publish the current resources of the device. See the next chapter.
resource update response message
{
	"nodeId": "HA0lQz8R",
	"updateCorrelationId": "5fc10d40e4332f0001aadf39",
	"status": "FAILED",
	"error": {
		"code": "myErrorCode",
		"details": "myErrorDetails"
	}
}
Field Description

nodeId

(Mandatory). Define the request’s targeted nodeId

updateCorrelationId

(Mandatory). The correlation id for this specific resource update (provided by the resource update request)

status

(Mandatory). Only the status "FAILED" is accepted.

error.code

(Optional) in case of failure, error code (String).

error.details

(Optional) in case of failure, error details (String).

The update process status can be retrieved with HTTP API, using Device management - Resources APIs

Publish the current device resources' versions in Live Objects

Live Objects allows your external connector to report the current resources' versions of a device. This can be done at any time. When a resource update is done on the device side (firmware update for instance), the device must report this new version in order to update the resource version declared on the Live Object platform.

The topic to publish is: connector/v1/current/resource

Current resource message
{
  "nodeId": "CLcl0F4b",
  "resources": {
    "my_specific_resource": {
      "version": "1.0"
    },
    "my_firmware": {
      "version": "3.2"
    }
  }
}
Field Description

nodeId

(Mandatory). Define the request’s targeted nodeId.

resources

(Mandatory). map of resource names. The "version" field value must be a "string"

"Application" mode

In addition to the 2 modes available for devices, the MQTT protocol can also be used for data exchange between a business application and Live Objects. In this mode, the protocol is used by a third party application which requires a reliable link with Live Objects.

Due to the specific use of this mode, it is subject to restrictions and security limitations..

To learn more about "application mode" using MQTTS protocol see.

Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC