Documentation

Mistake on this page? Email us

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.

    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.

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.

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.

    • 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

To view all devices, use the /v3/devices/ GET API.

To view device details for a specific device, use the /v3/devices/{id}/ GET API.

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.
  3. The Device details pane opens.
  4. Click the edit icon on any of the tabs.
  5. The Update device details pop-up window opens.
  6. Edit the device name or description (or both).
  7. 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.

  2. The Device details pane opens.

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

  4. Click the Actions button, and select Delete.

    A confirmation pop-up window opens.

  5. 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

Editing a device's name and description

To edit a device's name and description, use the /v3/devices/{id}/ PUT API.

Creating, editing and removing custom attributes

Create attributes using the /v3/devices/{device_id} PUT API, defining the attributes in the message body. When you give the value of a custom attribute:

  • Surround the value in quotation marks.
  • Escape inner quotation marks with a backward slash. See the example for Location below.

Note: You can add custom attributes to one device at a time.

Every time you use the API, you overwrite the previously defined custom attributes related to the device.

Device Management doesn't validate custom attributes. If you misspell an attribute or value, you'll create a new attribute-value pair. If you create a new device and try to give its Location attribute the value Camridge (missing b), Device Management will not indicate this error. Similarly, you might create a second attribute by spelling it Locaion (missing t), so you won't find Cambridge by filtering on Location.

To create the attribute Location and the value Cambridge, use the following request:

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

Note: Attribute-value pairs are case-sensitive. The attribute location is distinct from Location.

The device's entry in Device Directory now has "custom_attributes": {"Location": "Cambridge"},.

Filtering devices

You can filter devices based on criteria, such as:

  • Registration status. A toggle for viewing only the registered devices or devices in any state.
  • Lifecycle status
    • Enabled (connected).
    • Suspended (forced offline by administrator).
  • Device type
    • Directly connected (connected directly to Device Management).
    • Gateway connected (connected to Device Management through a gateway).
    • Gateways (the device is a gateway).
    • Edge gateways (the device is an Edge gateway).
  • Execution mode
    • Development.
    • Production.
    • Not set.

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. 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.
  2. 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.
  3. Click + Add another to combine multiple attributes in one filter.
  4. Click the Save icon, and give your filter a name.
  5. Click Save filter.
  6. 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.
  3. 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.
  3. The Saved filters pane with all the filters listed opens.
  4. Tick the checkbox next to the filter you want to edit. You can edit only one filter at a time.
  5. Click Actions, and select Edit filter.
  6. 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

Creating filters

  • To create a filter, use the /v3/device-queries POST API.

    You can refer to the filter using the id this interface returns. You can also append the filter to the URL of a request.

  • To create a multi-attribute filter, insert an ampersand (&) between attributes. You can also use multiple operators:

    state__eq=registered&lifecycle_status=enabled
    

    or, to find devices where state is registered and lifecycle status is not enabled:

    state__eq=registered&lifecycle_status__neq=enabled
    
  • To set a one-time device filter, which returns a list of devices but does not save the filter for later use, construct the filter and put it at the end of the URL in your request:

    GET /v3/devices?{filter}:
    

    For example:

       curl -X GET https://api.us-east-1.mbedcloud.com/v3/devices?lifecycle_status__eq=enabled \
       -H "Authorization: Bearer <api_key>"
    

    This lists devices with lifecycle status enabled. However, you can't use this type of filter to target devices in an update campaign.

Using a saved filter

  • To use a saved filter, call the /v3/device-queries/{query_id}/ GET API.

  • To list all filters in your account, use the /v3/device-queries GET API.

    For example:

    curl -X GET https://api.us-east-1.mbedcloud.com/v3/device-queries/
    -H "Authorization: Bearer <api_key>"
    

    This produces a list of all your filters:

    {
       "object":"list",
       "limit":50,
       "has_more":false,
       "after":null,
       "data":[
          {
             "object":"device-query",
             "updated_at":"2016-12-09T17:18:39.181780Z",
             "description":"",
             "id":"0158e4980a3200000000000100100001",
             "name":"Special Devices",
             "query":"name__eq=Special&Devices",
             "etag":"2016-12-09T17:18:39.181795Z",
             "created_at":"2016-12-09T17:18:39.181735Z",
             "query_id":"0158e4980a3200000000000100100001"
          },
          {
             "object":"device-query",
             "updated_at":"2016-12-12T11:51:12.856009Z",
             "description":"",
             "id":"0158f2df56d000000000000100100004",
             "name":"device-query: 0158f2de9992000000000001001001f8",
             "query":"id__eq=0158f2de9992000000000001001001f8",
             "etag":"2016-12-12T11:51:12.856024Z",
             "created_at":"2016-12-12T11:51:12.855975Z",
             "query_id":"0158f2df56d000000000000100100004"
          },
          {
             "object":"device-query",
             "updated_at":"2016-12-13T09:08:29.969605Z",
             "description":"",
             "id":"0158f770ba880000000000010010000a",
             "name":"Test Filter",
             "query":"mechanism__eq=connector",
             "etag":"2016-12-13T09:08:29.969626Z",
             "created_at":"2016-12-13T09:08:29.969532Z",
             "query_id":"0158f770ba880000000000010010000a"
          }
       ],
       "order":"ASC"
    }
    

Modifying a saved filter

To modify a saved filter, use the /v3/device-queries/{query_id}/ PUT API.

Deleting a saved filter:

To delete a saved filter, use the /v3/device-queries/{query_id}/ DELETE API.

Reference: Filter operators and built-in attributes

To create a filter, use the /v3/device-queries POST API.

You can refer to the filter using the id this interface returns. You can also append the filter to the URL of a request.

Creating multi-attribute filters

To create a multi-attribute filter, insert an ampersand (&) between attributes. You can also use multiple operators:

state__eq=registered&lifecycle_status=enabled

or, to find devices where state is registered and lifecycle status is not enabled:

state__eq=registered&lifecycle_status__neq=enabled

Setting one-time device filters

This method of filtering returns a list of devices, but does not save the filter for later use. Construct the filter, and put it at the end of the URL in your request.

Call `GET /v3/devices?{filter}:

  curl -X POST https://api.us-east-1.mbedcloud.com/v3/devices?lifecycle_status__eq=enabled \
  -H "Authorization: Bearer <api_key>"

This will list devices with lifecycle status enabled. However, you can't use this type of filter to target devices in an update campaign.

Listing created filters

To list all the filters in your account, call:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/device-queries/
-H "Authorization: Bearer <api_key>"

This produces a list of all your filters:

{
   "object":"list",
   "limit":50,
   "has_more":false,
   "after":null,
   "data":[
      {
         "object":"device-query",
         "updated_at":"2016-12-09T17:18:39.181780Z",
         "description":"",
         "id":"0158e4980a3200000000000100100001",
         "name":"Special Devices",
         "query":"name__eq=Special&Devices",
         "etag":"2016-12-09T17:18:39.181795Z",
         "created_at":"2016-12-09T17:18:39.181735Z",
         "query_id":"0158e4980a3200000000000100100001"
      },
      {
         "object":"device-query",
         "updated_at":"2016-12-12T11:51:12.856009Z",
         "description":"",
         "id":"0158f2df56d000000000000100100004",
         "name":"device-query: 0158f2de9992000000000001001001f8",
         "query":"id__eq=0158f2de9992000000000001001001f8",
         "etag":"2016-12-12T11:51:12.856024Z",
         "created_at":"2016-12-12T11:51:12.855975Z",
         "query_id":"0158f2df56d000000000000100100004"
      },
      {
         "object":"device-query",
         "updated_at":"2016-12-13T09:08:29.969605Z",
         "description":"",
         "id":"0158f770ba880000000000010010000a",
         "name":"Test Filter",
         "query":"mechanism__eq=connector",
         "etag":"2016-12-13T09:08:29.969626Z",
         "created_at":"2016-12-13T09:08:29.969532Z",
         "query_id":"0158f770ba880000000000010010000a"
      }
   ],
   "order":"ASC"
}

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.

    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.

  2. The Device details pane opens.

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

  4. Click the Actions button and select Delete.

    A confirmation pop-up window opens.

  5. 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

Create attributes using the /v3/devices/{device_id} PUT API, defining the attributes in the message body. When you give the value of a custom attribute:

  • Surround the value in quotation marks.
  • Escape inner quotation marks with a backward slash. See the example for Location below.

Note: You can add custom attributes to one device at a time.

Device Management doesn't validate custom attributes. If you misspell an attribute or value, you'll create a new attribute-value pair. If you create a new device and try to give its Location attribute the value Camridge (missing b), Device Management will not indicate this error. Similarly, you might create a second attribute by spelling it Locaion (missing t), so you won't find Cambridge by filtering on Location.

To create the attribute Location and the value Cambridge, use the following request:

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

Note: Attribute-value pairs are case-sensitive. The attribute location is distinct from Location.

The device's entry in Device Directory now has "custom_attributes": {"Location": "Cambridge"},.

References: Filter operators and built-in attributes

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

Filter operators

Operator in API and Portal advanced view Operator in Portal simple view Explanation
__eq is equal to Returns results exactly matching a string.
__neq is not equal to Returns results except those exactly matching a string.
__in is in This is similar to __eq, but can support a comma-separated list. Returns results exactly matching any of an array of possible values.
__nin is not in Supports a comma-separated list. Returns results except those exactly matching any of an array of possible values.
__lte is less than or equal to Returns results less than or equal to a given date-time value.
__gte is greater than or equal to Returns results greater than or equal to a given date-time value.

Device attributes and supported filter operators

Attribute parameter Attribute name in Device Management Portal Supported filter operators
account_id Devices in Portal are automatically sorted by account ID. eq
neq
in
nin
bootstrap_expiration_date Bootstrap expiration date in
nin
lte
gte
bootstrapped_timestamp Bootstrapped at in
nin
lte
gte
ca_id Certificate ID eq
neq
in
nin
connector_expiration_date Connector expiration date in
nin
lte
gte
created_at Created at in
nin
lte
gte
custom_attributes Custom attribute(s) eq
deployed_state Deployed state eq
neq
in
nin
deployment Deployment eq
neq
in
nin
description Description eq
neq
in
nin
device_class Class ID eq
neq
in
nin
device_execution_mode Execution mode eq
neq
in
nin
device_key Device key eq
neq
in
nin
endpoint_name Endpoint name eq
neq
in
nin
endpoint_type Endpoint type eq
neq
in
nin
enrolment_list_timestamp Enrollment list timestamp in
nin
lte
gte
etag E-tag eq
neq
in
nin
lte
gte
firmware_checksum Firmware checksum eq
neq
in
nin
groups Not in Portal
host_gateway Gateway host name eq
neq
in
nin
id Device ID eq
neq
in
nin
issuer_fingerprint Not in Portal
last_operator_suspended_category Last operator suspension category eq
neq
in
nin
last_operator_suspended_updated_at Last operator suspension date in
nin
lte
gte
last_system_suspended_category Last system suspended category eq
neq
in
nin
last_system_suspended_updated_at Last system suspension date in
nin
lte
gte
lifecycle_status Lifecycle status eq
neq
in
nin
manifest Manifest eq
neq
in
nin
manifest_timestamp Manifest timestamp in
nin
lte
gte
mechanism Mechanism eq
neq
in
nin
mechanism_url Mechanism url eq
neq
in
nin
name Device name eq
neq
in
nin
operator_suspended Operator suspended eq
neq
serial_number Serial number eq
neq
in
nin
state State eq
neq
in
nin
system_suspended System suspended eq
neq
updated_at Updated at in
nin
lte
gte
vendor_id Vendor ID eq
neq
in
nin