Device Manager

The agent code includes a device manager application that supports a set of predefined actions and device attributes to enable device management.

The device manager is a standalone application that uses the agent APIs to implement device management capabilities.

Paths to file locations depend on how you installed the agent code and the operating system on which you installed the agent.

All paths in this section are relative to the following base paths:

Agent

Installation Method

Base Path

Python

Download from GitHub

/path/To/device-cloud-python-release, where /path/To is the directory into which you downloaded the code.

Python

Install from the Python PyPI repository

Linux: /usr/local/share/device_cloud

Windows: pythonInstallDir\share\device_cloud

Python

Build into an image using the meta-device-cloud layer

Host: buildDir/build/tmp/sysroots/arch/usr/share/device_cloud, where buildDir is your build directory and arch is the processor architecture you build for

Target: /usr/share/device_cloud

C agent for Linux

Download from GitHub

/path/To/device-cloud-lib-release, where /path/To is the directory into which you downloaded the code.

C agent for VxWorks 7

Download from the GitHub vxworks_layer branch

/path/To/device-cloud-lib, where /path/To is the directory into which you downloaded the code.

The device manager source code and executable files are located as follows:

  • Python source code and executable: device_manager.py (the top level of the base directories)

  • C source code: src/device_manager

  • C executable on Linux: builddir/bin/iot-device-manager after you build the agent and /usr/local/bin/iot-device-manager after you run make install

  • C task on VxWorks 7: tManager

Note:

For VxWorks 7 with the Device Cloud components in your image and Yocto-based Linux distributions with the meta-device-cloud layer in your image, the device manager starts automatically when you boot the device.

For other operating systems, you must either start the device manager manually or configure the device manager to run as a service.

If you do not need the device management capabilities, including remote access, you do not need to run the device manager.

Application and Thing Definition

Both the Python and C implementation of the device manager requires the following application and thing definition in your organization in Device Cloud:

  • Application name: hdc_device_manager_app

  • Thing definition: hdc_device_manager_def

These components may exist when your organization is created. If not, run the setup-cloud-deps.py script in the share/admin-tools directory. You can run the script on any host or target with Python installed. To successfully add the definitions, you need to account credentials for an organization administrator. For more information, see the following:

To enable you to customize the device manager, create your own device manager thing definition and a new application to reference the thing definition for automatic registration. You can clone the hdc_device_manager_def as a starting point. For more information, see Device Cloud Management Portal User's Guide: Cloning a Thing Definition.

Run-Time Privileges on Linux

On the device, the device manager program should run without administrator or super user privileges. Add the user under which the device manager runs to the sudoers list. For an example for a user called device_cloud, see the share/sudoers.d/device_cloud file after installing the Python agent.

Device Cloud Application Privileges

By default, the hdc_device_manager_app is assigned the Device role with a restricted set of permissions. When you clone the device manager thing definition, ensure that the application that references the new thing definition has only the required permissions. The application should not run as an organization administrator. For more information about roles, see Device Cloud Management Portal User's Guide: Roles and Permissions.

Python Device Manager Command-Line Options

If you run the device manager from the command line or run the device manager as a service, for example, using systemd, you can specify command-line options for logging and configuration files. For more details, run device_manager.py --help.

Python Device Manager Configuration Files

The configuration files contain attribute-value pairs in JavaScript Object Notation (JSON) format.

On Linux-based operating systems, ensure that the user under which you run the device manager owns the configuration files or has read access.

You must store the files in the configuration directory specified in the source code. The default location is the same directory as the device_manager.py file.

iot-connect.cfg (mandatory)

Contains the connection configuration settings to enable the device manager to connect to Device Cloud. To generate the file, run the generate-config.py script on the device.

iot.cfg (mandatory)

Contains the configuration for the device manager behavior.

For details about the attributes and valid values, see iot.cfg Reference.

attributes.cfg (optional)

Contains custom attributes for the device manager. Create the file and store it in your configuration directory. For an example configuration file, see share/example_attributes_cfg.

In the device manager thing definition you create, you need to either add the new attributes or you need to enable Auto def attributes.

The attributes appear on the thing details page under the Attributes tab.

C Device Manager Configuration Files

The configuration files contain attribute-value pairs in JavaScript Object Notation (JSON) format.

You must store configuration files in the /etc/iot directory on your target device.

On Linux-based operating systems, ensure that the user under which you run the device manager owns the configuration files or has read access.

For information about adding the configuration files to the device for VxWorks 7, see Device Cloud Quick Start for VxWorks 7.

iot-connect.cfg (mandatory)

Contains the connection configuration settings to enable the device manager to connect to Device Cloud. To generate the file, run the iot-control script on the device.

This file is also the base connection configuration file. If multiple applications run on the device, the iot-connect.cfg file contains the common configuration settings and each client application specifies only the application token in the application-specific connection file. For more details, see Generating a Connection Configuration File for a C Application.

iot.cfg (optional)

Contains the configuration for the device manager behavior.

There is no default iot.cfg file; the device manger uses default values for the attributes. To change the behavior, create your own file based on the /etc/iot/iot.cfg.example file and rename it to /etc/iot/iot.cfg.

For details about the attributes and valid values, see iot.cfg Reference.

Methods and Attributes

The default device manager thing definition defines a set of attributes that provide information about the device on which the application runs. In addition to any custom attributes you defined, the attributes appear under the Attributes tab and include the following:

  • software version

  • host name

  • kernel version

  • MAC address (Python device manager only)

  • operating system name and version

  • relay version

  • system architecture

  • remote_access_support

The device manager thing definition defines the following methods that appear under the Methods tab on the device manager thing page. You can click the View icon of the device manager thing at Development Tools > Things > View icon > Methods.

Action

Description

Python Agent

C Agent on Linux

C Agent on VxWorks 7

Send Files

Sends a file to a specified directory on the device. You can specify either the full destination path name or use a path relative to the basePath/download directory. You must upload the file to either to the global file store or the thing file store before running the method. For details about sending files, see Sending a File to the Device.

basePath is the value of runtime_dir attribute in the iot.cfg file.

basePath is the /var/lib/iot directory

basePath is a subdirectory of the value specified for the DEVICE_CLOUD_AGENT_CONFIG_DIR parameter

Retrieve Files

Retrieves files from a specified directory on the device. You can specify either the full path on the device or a path relativebasePath/upload directory. For more details about retrieving files, see Retrieving a File from the Device. If you specify a directory and the upload_tar_file attribute in the iot.cfg file is true, all files in the directory are retrieved in a tar.gz file.

basePath is the value of runtime_dir attribute in the iot.cfg file.

basePath is the /var/lib/iot directory.

basePath is a subdirectory of the value specified for the DEVICE_CLOUD_AGENT_CONFIG_DIR parameter.

Update Remote Access Ports

Update dynamic services, for example, VNC server, SSH, and so on. You can now refresh the remote access attribute with an updated list of ports. The discover_services_on_init attribute in the iot.cfg file is set to true by default and is used to scan service ports on startup. For more information, see iot.cfg Reference.

basePath is the value of discover_services_on_init attribute in the iot.cfg file.

basePath is the /var/lib/iot directory.

Not supported.

Reboot Device

Remotely reboots the device.

Supported only in kernel mode.

Remote Login

For internal device manager use only.

For information about remote access to devices, see the Device Cloud Remote Access User's Guide.

Shutdown Device

Turns off the device. To restart it, you need physical access to the device.

Supported only in kernel mode on Intel BSPs or other BSPs that support shutdown.

Reset Agent

Restarts the device manager on the device.

Supported only when the device manager runs as a service (systemd_controlled is set to true in the device_manager.py file).

Not supported.

Not supported.

Decommission Device

Removes all information, including certificates and credentials, that enables the device to communicate with Device Cloud. It also removes agent-related files that may contain information that affects the security of the device or the network.

Supported only in kernel mode on Intel BSPs or other BSPs that support shutdown. Provides the same functionality as the Shutdown Device method.

Update Device Software

Updates the device software. For more details about updating the device software, see Updating the Device Software.

For examples of the required package instructions and package format, see the basePathshare/example-ota-packages directory.

For examples of the required package instructions and package format, see the basePathshare/example-ota-packages directory.

Supported only in kernel mode. For examples, see the basePath/build-sys/vxworks-layer-for-device-cloud-lib/sample-rtp-ota and basePath/build-sys/vxworks-layer-for-device-cloud-lib/sample-dkm-ota directories.

The device manager cannot update itself.

Workflow

The workflow to configure and run the device manager in a production environment is as follows:

  1. Create a copy of the device manager thing definition. For more information, see Device Cloud Management Portal User's Guide: Cloning a Thing Definition.

  2. Create a new application and select the thing definition you created for automatic registration. For more information about creating applications, see Device Cloud Management Portal User's Guide: Defining Applications.

    You need organization administrator privileges to create applications.

  3. Generate the device manager connection configuration file and specify the application token of the application you created. For more information, see the following:

  4. Change the configuration of the device manager to match your requirements and operating system environment.

  5. Run the device manager.