Devices

A device can be a physical sensor or a virtual resource, such as the data generated by a third-party API. Data against a device is stored as Device Attributes in a time series database, and from there the data can be acted on, analyzed, and visualized using other components of Losant.

A list of your application’s devices can be found under the “Devices” tab in the application menu.

Adding a Device

To add a new device, click the “Add Device” button at the top of your devices list.

Add Device

Choosing a Device Type

Clicking “Add Device” will take you to a screen where you will choose which type of device to create. While you may change this type after creation (except when creating a system or trying to change a device’s type to a system), doing so can be disruptive to your application; therefore, you should know which type of device you’d like to create before proceeding.

Device Type

  • Standalone
    A Standalone device is your normal everyday type of device. It is allowed to connect directly to Losant and report its own state. In most cases, this is the device type you will choose. If your device data is generated by a third-party API, it can be represented as a Standalone device in Losant.
  • Gateway
    A Gateway device is a device that connects to Losant and reports both its own state and the state of other devices - i.e., other devices that use this device as a “gateway”. Gateways are extremely useful for helping to report the state of non-internet connected devices to Losant - such as Bluetooth sensors.
  • Edge Compute
    An Edge Compute device is a device that runs the Losant Edge Agent and can run edge workflows directly on the device itself. They also can behave as Gateway devices, in that they may report state on behalf of a Peripheral device.
  • Peripheral
    A Peripheral device does not connect directly to Losant - instead it reports its state either to a Gateway or Edge Compute device (which is connected to the internet), and that gateway pushes the peripheral’s state to Losant. When choosing peripheral as the device type, there are two options. You can either choose to let the device report state through any gateway in the application (which is useful for devices that move through the range of multiple gateways), or you can choose to only allow reporting through a specific gateway (useful for static or directly connected devices).
  • System
    A System device behaves more as a grouping mechanism - and a model of a larger physical environment - than a typical device. Systems cannot connect to the platform, report their own state, nor receive commands; instead, their state attributes are an aggregation of the raw data reported by their child devices. As noted above, unlike the other types, a device’s type cannot be changed to or from a system after creation.

Device Configuration

After choosing a device type, you will then be asked to fill in the following information:

Device Configuration

  • Name: Enter a human-readable name for the device. This field is required, and we highly recommend (but do not require) it be unique across the application.
  • Description: Optionally, you may also include a longer explanation of the device.
  • Device Class: Though this was chosen on the previous page, you have the option of modifying the device class before creation here.
  • Reporting Gateway: This section is only present if “Peripheral” is chosen for the device class. You must choose if this device’s state can be reported by any gateway device or only by a specific gateway.
  • Parent System: Optionally, you may assign this device as a child of any existing system.
  • Device Tags: You may enter a set of key/value pairs as tags on the device. More info on how to use device tags can be found below.

After you’ve configured your device, click “Create Device” at the bottom of the form. This will add the device to your application and will redirect you to an interface where you can define the new device’s state attributes.

Other Ways to Add Devices

In addition to adding a new device from your device list, there are a couple of other methods by which a device can be created:

Device Tags

Device tags allow you to group and organize your devices. Tags are defined as keys and values and they can be set to anything you’d like. Tags can be used in many other areas of the Losant Platform including choosing devices for visualizations, access keys, and workflow triggers. See the section on device queries for targeting devices by tag within the platform.

Tags are also a great place to store things like device configuration or threshold values, as the tag keys and values for a device are available to use within workflows (both in the cloud and on the edge) as well as in a number of the dashboard blocks.

Device Tags

In the above example, the floor tag is set to the value of 2 and the color tag is set to red. If you had many devices on different floors and of different colors, you could easily query all devices where floor=2 or color=red to find the specific devices.

Device Debugging

Once the device is added, there are several useful pieces of information available in the right column on the device page.

Device Communication Log

The device communication log is similar to the application log in that it displays a real-time stream of events; it differs from the application log in that these events are specific to the device currently being viewed, instead of across the application as a whole. A number of different events will display within the log, such as:

  • State reports for the device, whether they come via the device itself through the Losant broker, via a workflow, or through the Losant REST API.
  • Commands sent to the device, delivered via any of the channels mentioned above.
  • Device connection, disconnection, and authentication events. For peripheral devices, the log will display these events for the peripheral’s gateway.

Device Log

Arbitrary topics the device publishes to or is subscribed to will not display within the device communication log.

Connection Status

The current connection status of your device is always available within the Connection Log panel. For peripheral type devices, the connection status of the gateway device it is configured to use is displayed.

For Standalone and Gateway type devices, you can also view a log of recent device connection events in the Device Connection Log of the Connection Log panel.

Connection Log

Whenever a device is disconnected, the log will contain the reason and - if the connection events happened over the MQTT broker - the number of messages sent and received during the connected period. Typically messages sent correspond to state updates and messages received correspond to commands. The list will automatically update as new connection events come in.

Recent Device States

Recent Device States

This list will display the 25 most recent states published to Losant by this device. It displays the raw JSON data that represents a state request. This list will automatically update as new state requests come in.

Other Device Actions

From the device’s detail page, there are a number of additional actions you can take against the device. These can be reached from the dropdown menu in the top right corner of the page.

Device Other Actions

Note: If you have any unsaved changes on the device (i.e. you’ve updated its name or added an attribute but not yet clicked the “Save” button), these other actions are unavailable.

Depending on the type of device and your permissions within the application, some of these actions may not be available.

Force State

Forcing device state is an excellent way to debug workflows, dashboard blocks, or other actions that are triggered by a device state report.

Force Device State

Enter values for each of the device state attributes you’d like to report. Note that we do not validate that the value entered for a state attribute is valid for its data type - nor do we ensure that an attribute actually exists on the device - so that you may also debug invalid state reports through the modal.

Send Command

If you have code on your device that is listening for commands sent from the platform - or, in the case of edge compute devices, if you have workflows with Device: Command Triggers deployed to the device - you can debug that functionality by sending a command here.

Send Command

Enter a command name and optionally a payload to send to the device. Note that the device must have an open connection to the MQTT broker to receive the command.

Request Data Export

You can request a CSV export of the state data that Losant has for your device. This will generate a CSV file of the state data for your device and send you an email when the generation is complete. The email includes a link that will allow you to download the generated file (the link is time-sensitive and will only work for 24 hours).

Request Data Export

Enter an email address for where to send the data export (the default is your user email) and optionally choose a time range of the data you would like to receive (the default is all available device data).

The generated CSV will have a timestamp column (where the timestamp will be represented as milliseconds since epoch), an ISO Date column (where the time is represented in human-readable form), as well as columns for any attributes of your device. Each row will represent one reported state for the device. The following is an example export for a device with a “location” and a “temperature” attribute:

Timestamp,ISO Date,location,temperature
1467391295000,"2016-07-01T16:41:35.000Z","17.06025867,-18.96596512",25.2
1467391325000,"2016-07-01T16:42:05.000Z","15.44856967,-17.68055596",25.1
1467391355000,"2016-07-01T16:42:35.000Z","14.08786621,-16.61800051",25.2
1467391385000,"2016-07-01T16:43:05.000Z","12.58478405,-15.46545390",25.3
1467391415000,"2016-07-01T16:43:35.000Z","11.08683392,-14.33618457",25.3

Delete Data

If you would like to delete data stored against the device - for example, if you’ve been debugging with forced report states and you do not want to save that data - you may do so from the dropdown menu.

Delete Device Data

Choose whether to delete all data associated with the device, or just a range of data given a start and an end time. Before deleting, you must also acknowledge that you understand the move is permanent and cannot be undone.

Create Access Key

To create an access key that will allow this device to connect to Losant’s MQTT broker, click the “Create Access Key” link This will display a modal with the new access key credentials and an option to download the access key as a file.

New Access Key

This access key will be scoped only to this device; it cannot be used to connect any other device to the broker.

Clone Device

To create a new device with the same configuration as the current device, choose the “Clone Device” option from the dropdown. This will add a new device with the same configuration to your application and will redirect you to the new device, where you can make additional changes if desired.

Note: If you are cloning a system, and the device has any attributes that are referencing specific devices, those devices will be removed from the configuration in the cloned device.

Convert to Recipe

You may also wish to convert your existing device to a device recipe in order to create a large number of devices with the same configuration. Click the “Convert to Recipe” option, and then you will be redirected to the newly created recipe.

Just like with cloning a system, any attributes referencing specific devices will have those devices removed from configuration before creating the recipe.

Deleting a Device

To delete a device, click the “Delete Device” button at the bottom of the “Properties” tab. This will display a modal requiring you to confirm the action by typing the device name.

Delete Device Modal

Deleting a device will also delete all data associated with the device. This action cannot be undone.

Exporting Devices

Export Devices

To export a list of all the devices scoped to an application, visit the “Devices” page and click the “Export All Devices” button in the top right corner of the list. This generates a CSV file of all devices in the application for download, which will be emailed to you after the export has completed. The CSV will include each device’s name, ID, description, device type, gateway device ID, parent device ID, and each tag associated with the device.

Note that device exports always include the application’s entire device list, not just the devices that are currently displayed in the interface (as filtered by name or paginated).