Viewing and editing device details

When a device that belongs to you connects to Device Management for the first time and authenticates itself, Device Management registers the device and device-related information - including the device name, description and various device attributes - in your account's Device Directory.

An attribute is device-related information that enables identifying, grouping or filtering devices.

Devices have two types of attributes:

• Built-in attributes: Information that exists on the device, including:

  • Device ID: A globally unique ID that Device Management automatically generates when the device first connects to the Device Management.
  • Endpoint name: A name you can give your device in the factory.
  • Serial number: Populated from the device's firmware.
  • Vendor ID: Populated from the device's firmware.
  • Device class: The type ID of the device.
  • Component: This consists of a key-value pair of component name and version. With this attribute, you can distinguish between the main firmware and other modules or sensors on a device, for example, when you create a filter for an update campaign. This feature is available to selected customers. Please contact us for more information.

  For the full list of built-in attributes, see Filter operators and built-in attributes.

• Custom attributes: Information you define in Device Management. This information is not on the device - the device doesn't provide it and doesn't store it.

  Custom attributes let you create specific filters that can make device management and firmware update easier; for example:

  • Distinguish between test and deployment devices.
  • List the OS full version.
  • Indicate factory name.
  • Identify device location, such as city or street.

  You can assign up to five custom attributes to a device and up to ten custom attributes to a device group.

  Note: Device group custom attributes apply only to the group and are not passed down to the devices within the group.

Device Directory lets you view and edit device properties and attributes, filter devices and carry out activities on sets of devices.

You can carry out all of these activities on the Device Directory page of Device Management Portal or using the Device Management service APIs.

For information about viewing and managing gateway devices and the Pelion Edge gateway solution in general, please see the Pelion Edge documentation.

Viewing device details

You can view the details of a single device, or you can retrieve the details of a set of devices using device filters.

In Portal: Viewing device details

To view all details related to a device:

1. Go to Device directory > Devices in Device Management Portal.

2. Click a Device ID from the list of devices.

   The Device details pane opens with these tabs:

   • Summary lists general information about the device.

     • If the device belongs to a device group, there is a direct link to the group (Device group page).
     • If the certificate with which the device registered to Device Management is still valid, there is a link to the certificate details (Certificate details page).

   • Attributes lists the attributes associated with the device, by which you can identify, group or filter the devices. For more information about attributes, see Setting custom attributes.

   • Resources lists the Resources on a device.

     • If the device has Resources, the Path links you to further information on the selected Resource.

   • Events log lists device events, such as the device's first registration date and all firmware updates.

     For more information about device events, please see Viewing device events.

     • The Message text links you to further information on the event.

Using the API: Viewing device details

Editing device details

You can edit a device's name and description and add, delete or modify custom device attributes.

In Portal: Editing device details

To edit a device's name and description:

1. Go to Device directory > Devices in Device Management Portal.

2. Click the Device ID of the desired device or gateway.

   The Device details pane opens.

3. Click the edit icon on any of the tabs.

   The Update device details pop-up window opens.

4. Edit the device name or description (or both).

5. Click Save to confirm your changes.

To add custom attributes:

1. Click the Device ID of the desired device.

   The Device details pane opens.

2. On the Attributes tab, click the Add button.

   The Add custom attribute pop-up window opens.

3. Give a name and value to the new attribute, and click Save.

   The new attribute is added to the list of attributes associated with the selected device.

To remove custom attributes:

1. Click the Device ID of the desired device.

   The Device details pane opens.

2. On the Attributes tab, tick the checkbox next to one or multiple attributes.

3. Click the Actions button, and select Delete.

   A confirmation pop-up window opens.

4. Click Delete to confirm the removal.

To edit custom attributes:

1. Click the Device ID of the desired device.

   The Device details pane opens.

2. On the Attributes tab, tick the checkbox next to one or multiple attributes.

3. Click the Actions button, and select Edit.

   A pop-up window opens.

4. Change the attribute name or value or both, and click Yes to confirm your changes.

Using the API: Editing device details

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/devices/0158f770ba880000000000010010000a
    -H "Authorization: Bearer <access_key>" \
    -H "Content-Type: application/json" \
    -d '{"custom_attributes": "{\"Location\":\"Cambridge\"}"}'

Filtering devices

You can filter devices based on criteria, such as registration status, lifecycle status, device type, and execution mode.

A filter must be:

• Complete: Partial attributes or attribute values return no results.
• Exact: Filters retrieve exact attribute matches and are case-sensitive. For example, Location is distinct from location.
• A string: Filters only accept strings (which can include numbers). Leaving an attribute value blank returns only devices that have no value for that attribute. You can also filter by Boolean values.

See the full list of attributes and operators.

In Portal: Filtering devices

To create a new filter:

1. Go to Device directory > Devices in Device Management Portal.

2. On the grey bar above the list of devices, click the arrow next to Filters.

   • The default view for creating a filter is Simple view.
   • If you want to create your filter using a raw query string instead, click Advanced view. See Filter operators and built-in attributes for details.

3. From left to right, choose an attribute, for example Device ID, an operator, and give a value. You can also choose an attribute that applies to multiple devices.

4. Click + Add another to combine multiple attributes in one filter.

5. Click the Save icon, and give your filter a name.

6. Click Save filter.

   Your filter is applied, and the page lists the devices matching your selected attributes and their values.

To use a saved filter:

1. On the Devices page, click Saved filters to open a list of available ready-made filters.

2. Select a filter that matches your needs.

   Your filter is applied, and the page shows the filter name and lists the devices matching your selected attributes and their values.

You can now select the filtered items and perform actions on them.

To modify a saved filter:

1. On the Devices page, click Saved filters to open a list of ready-made filters available.

2. Click Manage saved filters at the bottom of the list.

   The Saved filters pane with all the filters listed opens.

3. Select the checkbox next to the filter you want to edit. You can edit only one filter at a time.

4. Click Actions, and select Edit filter.

5. Continue in the same way as in creating a new filter.

To rename a filter, click the Rename icon and give a new name in the opening window. Click Rename filter to confirm the new name.

To delete a saved filter:

1. On the Devices page, click Saved filters to open a list of ready-made filters available.

2. Click Manage saved filters at the bottom of the list.

   The Saved filters pane with all the filters listed opens.

3. Tick the checkbox next to one or multiple filters you want to delete.

4. Click Actions, and select Delete filters.

5. In the opening window, click Delete to confirm.

You can also select Edit filter to see first the details of the filter and then click the Delete icon.

Using the API: Filtering devices

Setting custom attributes

An attribute is a piece of device-related information that enables identifying, grouping or filtering devices.

Devices have two types of attributes:

• Built-in attributes: Information that exists on the device, including:

  • Device ID: A globally unique ID that Device Management automatically generates when the device first connects to the Device Management.
  • Endpoint name: A name you can give your device in the factory.
  • Serial number: Populated from the device's firmware.
  • Vendor ID: Populated from the device's firmware.
  • Device class: The type ID of the device.
  • Component: This consists of a key-value pair of component name and version. With this attribute, you can distinguish between the main firmware and other modules or sensors on a device, for example, when you create a filter for an update campaign. This feature is available to selected customers. Please contact us for more information.

  For the full list of built-in attributes, see Filter operators and built-in attributes.

• Custom attributes: Information you define in Device Management. This information is not on the device - the device doesn't provide it and doesn't store it.

  Custom attributes let you create specific filters, which can make device management and firmware update easier; for example:

  • Distinguish between test and deployment devices.
  • List the OS full version.
  • Indicate factory name.
  • Identify device location, such as city or street.

  You can assign up to five custom attributes to a device, and up to ten custom attributes to a device group.

  Note: Device group custom attributes apply only to the group, and are not passed down to the devices within the group.

  You store custom attributes in Device Directory, not on the device. This means that the client running on the device is unaware of these attributes. If you want the client to be aware of a custom attribute, you need to give the device a Resource with this attribute.

In Portal: Setting custom attributes

You can add, remove or edit your custom attributes.

To add custom attributes:

1. Click the Device ID of the desired device.

   The Device details pane opens.

2. On the Attributes tab, click the Add button.

   The Add custom attribute pop-up window opens.

3. Give a name and value to the new attribute and click Save.

   The new attribute is added to the list of attributes associated with the selected device.

To remove custom attributes:

1. Click the Device ID of the desired device.

   The Device details pane opens.

2. On the Attributes tab, tick the checkbox next to one or multiple attributes.

3. Click the Actions button and select Delete.

   A confirmation pop-up window opens.

4. Click Delete to confirm the removal.

To edit custom attributes:

1. Click the Device ID of the desired device.

   The Device details pane opens.

2. On the Attributes tab, tick the checkbox next to one or multiple attributes.

3. Click the Actions button and select Edit.

   A pop-up window opens.

4. Change the attribute name or value or both and click Yes to confirm your changes.

Using the API: Setting custom attributes

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/devices/0158f770ba880000000000010010000a
    -H "Authorization: Bearer <access_key>" \
     -H "Content-Type: application/json" \
     -d '{"custom_attributes": "{\"Location\":\"Cambridge\"}"}'

Component attributes

Note: This feature is available to select customers only.

Components are sensors, chips, or other parts of a device that can have their own firmware. Component names and versions consist of a string and semantic version (x.x.x). These initial values are built-in attributes that are on the device when it leaves the factory, so you can filter by them the same way as any other attribute.

In Device Management Portal: Component attributes

See In Portal: Filtering devices above for generic instructions that apply to filtering by component attributes.

Using the APIs: Component attribute examples

curl -X POST https://api.us-east-1.mbedcloud.com/v3/device-queries \
         -H 'Authorization: Bearer <api_key>' \
         -H 'content-type: application/json' \
         -d '{ "name": "Example query name", "query": "component_attributes__Main__eq=1.0.0"}'

curl -X POST https://api.us-east-1.mbedcloud.com/v3/device-queries \
         -H 'Authorization: Bearer <api_key>' \
         -H 'content-type: application/json' \
         -d '{ "name": "Example query name", "query": "component_attributes__Main__eq=1.1.0&component_attributes__ble__eq=2.2.2"}'

References: Filter operators and built-in attributes

These tables apply to both the APIs and Device Management Portal.

Filter operators

Device attributes and supported filter operators