Device Cloud Agent

Data Model

The capabilities of a client application on the device are specified in the thing definition in Device Cloud. Client applications do not advertise their capabilities to Device Cloud; they implement the capabilities defined in the thing definition. Before a client application can register successfully with Device Cloud, the corresponding thing definition must exist. Client applications are instances of thing definitions, referred to as things in Device Cloud, and are identified in Device Cloud by a unique thing key. You can view and define applications on the Management Portal on the Thing Definitions page, which is accessed from the Developer page.

Client applications also require a representation of the application in Device Cloud, which establishes the association between the thing definition and the client application (thing). An organization administrator must predefine the corresponding application in Device Cloud before a client can register successfully. You can view and define applications on the Management Portal on the Applications page, which is accessed from the Developer page.

To enable automatic registration, the application definition in Device Cloud must specify the thing definition with which it is associated. To enable manual registration, the thing must be defined in Device Cloud with a unique thing key and the client application must register using the predefined thing key. For more information about how the agent generates the thing key, see Device Cloud Device Programmer's Guide: Device Cloud Client Applications.

C Applications

The agent supports the same functionality as agent release 2.1 and later. However, the terminology used in the APIs is different from the terminology on the Management Portal and in the thing definition as follows:

• Numeric telemetry items are defined as properties in the thing definition and appear in the Properties section on the thing details page.

• String telemetry items are defined as attributes in the thing definition and appear under the Attributes tab on the thing details page.

• Actions are defined as methods in the thing definition and appear under the Methods tab on the thing details page.

The C APIs are backward compatible with agent release 2.1 and later with the following exceptions:

• String telemetry is implemented through attributes instead of telemetry. The agent provides new APIs to publish string telemetry.

• The agent does not support an API to specify units for telemetry.

The following APIs are deprecated:

• iot_telemetry_attribute_set

• iot_telemetry_attribute_set_raw

• iot_action_attribute_set

Python Applications

A native, cross-platform Python agent with a new, simplified set of APIs replaces the bindings to the C APIs. Sample applications demonstrating the APIs are provided. For API reference information, run pydoc device_cloud from top level of the agent source directory.

Device Management

The device manager is now a standalone application that provides the device management actions previously implemented by the agent and accessed through the STANDARD ACTIONS and CUSTOM ACTIONS on the management console, including shutdown, agent reset, reboot, file transfer, device decommissioning, and software update. You run the actions from the device manager thing details page under the Methods tab.

To send files to a device, you must now upload them to the Management Portal first before running the Send Files method. For more information, see Device Cloud Device Programmer's Guide: File Transfer.

The remote login action is accessed from the LaunchPad through the Device Console link and does not require a separate component (the MUX) on the device; the device manager application implements the required functionality. Connectivity is through the Telnet protocol on port 23. You need to install a Telnet server on your device to enable remote access.

The device manager is an optional component; you do not need to run it on your device if you do not need the device management functionality or remote access to the device.

There is no iot-device-manager systemd service in Linux or corresponding Windows service to start and stop the device manager automatically. Example service configuration files are provided with the agent source code.

The device manager is available as both a Python and C application.

For more information about the device manager, see Device Cloud Device Programmer's Guide: Device Manager.

Authentication

The startup.bin file does not apply to the new platform. To authenticate the client application with Device Cloud, the client application uses an application-specific configuration file that specifies a globally unique application token, the organization-specific Device Cloud endpoint, and the port number to use. This information is used when the application connects to Device Cloud and authenticates with the corresponding organization. The application token is available on the Applications page and the endpoint is available on the Developer page on the Management Portal.

The files dxlpolicy.bin and agentguid.bin do not apply to the new platform and are not created on the device at registration time. Applications are identified in Device Cloud based on a unique thing key instead of the agent GUID, which previously appeared on the management console as the device identifier. Each application that registers with Device Cloud must use a different thing key. If another application attempts to register using the same thing key, registration fails. The agent provides support for generating a unique thing key, and unlike the agent GUID, it is not based on the MAC address of the network interface. For more information about thing keys, see Device Cloud Getting Started: Device Cloud Agent.

Connectivity

Each client application communicates directly with Device Cloud; the application does not connect through the agent. There are no iot and iot-ccg systemd services in Linux or corresponding Windows services.

Client applications communicate with Device Cloud over a single port. Ports 443, 8883 (secure MQTT), or 1883 (insecure MQTT) are supported, and the port to use is specified in the application connection configuration file. The use of standard protocols enables network management systems to monitor compliance through deep packet inspection. Only the Python agent on Linux supports port 443.

Messaging uses MQTT QOS 1 by default and messages from client applications are queued for retransmission when the device is offline.

For more information about Device Cloud connectivity, see Device Cloud Getting Started: Device Cloud Connectivity.

Configuration Files

All configuration files are in JSON format.

iot.cfg (changed)

Custom device properties, such as serial number and model, have been removed. Applications can use the agent APIs to specify custom properties as attributes.

appName-connect.cfg (new)

• Contains the configuration settings to enable an application to connect to Device Cloud, including the application token, endpoint, and proxy settings.

• Each application requires a connection file.

iot-connect.cfg (new)

Contains the device manager connection configuration.

attributes.cfg (new)

Contains optional custom attributes for the device manager.

iot-proxy.cfg (removed)

Configuration settings are now part of the application-specific connection configuration file and the iot-connect.cfg file for the device manager.

iot-mux.cfg (removed)

The MUX component is no longer required.

File Transfer

Files uploaded from either a computer or a device are stored as follows:

• in the global file storage, which you access from the Developer page

• in the thing-specific file storage, which you access from the thing details page under the Files tab

In addition to downloading files to a device from these locations, you can download stored files to a computer.

File transfer between the device and Device Cloud is supported through device manager methods and agent APIs. Files can be uploaded and downloaded from any location on the device.