"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"
Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC