Device Info (API)

There are APIs for getting or setting information on a device. The information can include the battery percentage and device name. In this section, we'll describe how you can do this via simple workflow actions.

📘
URN Type for Getting/Setting Device Information
When getting or setting device information, for the required target you can use either a device urn or an interaction urn. This is one of the less-common cases where the target does not have to be an interaction urn.

Device Information Overview

In your workflow you can use methods that retrieve information on the device. Some information that might be useful is the device's location, which is discussed in the Location section. Other information includes the device battery percentage, device name, device ID, and device type. The main parameter that you will need for these functions is the target, which can be a device urn or an interaction urn. You may also notice a 'refresh' parameter: this is just asking whether or not you would like to refresh the data or use an existing cached value. If you decide to refresh before retrieving information on the device, it may take a few more seconds to get the information. If you decide not to, the function will retrieve the data quickly by using the cached value.

The sample code below demonstrates how to use these methods:

const battery = await workflow.getDeviceBattery(source_uri, true)
// 94 (int)
const id = await workflow.getDeviceId(source_uri)
// "990007560012345"
const name = await workflow.getDeviceName(source_uri)
// "alice"
const type = await workflow.getDeviceType(source_uri)
// "relay2"

battery = await workflow.get_device_battery(source_uri, true)
# 94 (int)
id = await workflow.get_device_id(source_uri)
# "990007560012345"
name = await workflow.get_device_name(source_uri)
# "alice"
type = await workflow.get_device_type(source_uri)
# "relay2"

var battery = await Relay.GetDeviceBattery(this, source_uri, true);
// 94 (int)
var id = await Relay.GetDeviceId(this, source_uri);
// "990007560012345"
var name = await Relay.GetDeviceName(this, source_uri);
// "alice"
var type = await Relay.GetDeviceType(this, source_uri);
// "relay2"

int battery = relay.getDeviceBattery(sourceUri, true);
// 94 (int)
String id = relay.getDeviceId(sourceUri, false);
// "990007560012345"
String name = relay.getDeviceName(sourceUri, false);
// "alice"
String type = relay.getDeviceType(sourceUri, false);
// "relay2"

battery := api.GetDeviceBattery(sourceUri, true)
// 94 (int)
id := api.GetDeviceId(sourceUri, false)
// "990007560012345"
name := api.GetDeviceName(sourceUri, false)
// "alice"
i_type := api.GetDeviceType(sourceUri, false)
// "relay2"

Setting Information

There are also methods for setting some information on the device, such as the name of the device, its channel, and the mode. For example, using the setDeviceName() method lets you change the name of a device. This action is equivalent to using Dash to change the device name. The new name will also be displayed in Dash.

To change the device's channel, you can use the setDeviceChannel() method. This allows you to change the device's channel if you have multiple different groups, or switch back to the Relay Assistant channel. To use this method, you would need the URN of the device and the name of the channel that you would like to switch to as a string. The device will remain on this channel until it is switched again with the Assistant button or this method is invoked again.

Enabling/Disabling Location Services

You can also choose to enable or disable the device's location services. This is equivalent to toggling the device's Location Tracking enablement in Dash. If you choose to enable the device's location services (which are disabled by default), then you will be able to use the capabilities discussed in the Location section. This includes getting the device's indoor and outdoor location.

Example

The following is an example of an interaction that changes the device's name and channel.

workflow.on(Event.INTERACTION_STARTED, async({source_uri: interaction_uri}) => {
  // Change the device's name
  const originalName = await workflow.getDeviceName(interaction_uri)
  await workflow.say(interaction_uri, `This is my original name: ${originalName}`)
  await workflow.setDeviceName(interaction_uri, 'Barbara')
  const newName = await workflow.getDeviceName(interaction_uri)
  await workflow.say(interaction_uri, `This is my new name: ${newName}`)
  
  // Change the device's channel
  await workflow.setDeviceChannel(interaction_uri, 'Engineering')   
})

@my_workflow.on_interaction_lifecycle
async def lifecycle_handler(workflow, itype, interaction_uri, reason):
    if itype == relay.workflow.TYPE_STARTED:
        # Change the device's name
        originalName = await workflow.get_device_name(interaction_uri)
        await workflow.say(interaction_uri, f'This is my original name: {originalName}')
        await workflow.set_device_name(interaction_uri, 'Barbara')
        newName = await workflow.get_device_name(interaction_uri)
        await workflow.say(interaction_uri, f'This is my new name: {newName}')

  			# Change the device's channel
  			await workflow.set_device_channel(interaction_uri, 'Engineering')

public override async void OnInteractionLifecycle(IDictionary<string, object> dictionary)
{
  var type = (string) dictionary["type"];

  if (type == InteractionLifecycleType.Started)
  {
    // Change the device's name
    var originalName = await Relay.GetDeviceName(this, interaction_uri);
    await Relay.Say(this, interaction_uri, $"This is my original name: {originalName}");
    await Relay.SetDeviceName(this, interaction_uri, "Barbara");
    newName = await Relay.GetDeviceName(this, interaction_uri);
    await Relay.Say(this, interaction_uri, f"This is my new name: {newName}");

    // Change the device's channel
    await Relay.SetChannel(this, interaction_uri, "Engineering");
  }

@Override
public void onInteractionLifecycle(Relay relay, InteractionLifecycleEvent lifecycleEvent) {
  super.onInteractionLifecycle(relay, lifecycleEvent);

  String interactionUri = (String)lifecycleEvent.sourceUri;
  
  if (lifecycleEvent.isTypeStarted()) {
    String originalName = relay.getDeviceName(interactionUri, true);
    relay.say(interactionUri, "This is my original name: " + originalName);
    relay.setDeviceName(interactionUri, "Barbara");
    String newName = relay.getDeviceName(interactionUri, true);
    relay.say(interactionUri, "This is my new name: " + newName);

    // Change the device's channel
    relay.setChannel(interactionUri, "Engineering");
  }

api.OnInteractionLifecycle(func(interactionLifecycleEvent sdk.InteractionLifecycleEvent) {
  log.Debug("User workflow got interaction lifecycle: ", interactionLifecycleEvent)

  if interactionLifecycleEvent.LifecycleType == "started" {
    originalName := api.GetDeviceName(interactionUri, true)
    api.Say(interactionUri, "This is my original name: " + originalName, sdk.ENGLISH)
    api.SetDeviceName(interactionUri, "Barbara")
    newName := api.GetDeviceName(interactionUri, true)
    api.Say(interactionUri, "This is my new name: " + newName, sdk.ENGLISH)

    // Change the device's channel
    api.SetChannel(interactionUri, "Engineering")
  }

Other Ways to Get Information

If you have the device ID and your subscriber ID, you can do an HTTP GET to get a JSON payload with more information regarding your device. This JSON payload has a lot more data than is available in the methods above. For instructions on this, take a look at the Device Info (HTTP) section.

📘URN Type for Getting/Setting Device Information

Device Information Overview

Setting Information

Enabling/Disabling Location Services

Example

Other Ways to Get Information

📘
URN Type for Getting/Setting Device Information