description
You can display the power status of your end users' devices in your app.

Displaying Device Power Status

You can display the power status of your end users' devices in your app, including whether the device is wired or battery-powered. Further, for battery-powered devices, you can also display information about the battery status, such as the battery charge level and the battery status.

To display this information, use either of the following Seam mechanisms:

Use the properties.has_direct_power, and properties.battery properties of the device object.
Use the device.low_battery and device.battery_status_changed events.

Get Device Power Status Using Device Properties

Seam polls connected devices and accounts every ten minutes and updates the following device properties accordingly:

Property	Type	Description
`properties.has_direct_power`	Boolean	Indicates whether the device has direct power, that is, whether the device is wired
`properties.battery`	Object	Battery information, including `level` and `status`
`properties.battery.level`	Number (0-1)	Battery level of the device as a decimal value between 0 and 1, inclusive
`properties.battery.status`	Enum (string)	Current status of the battery charge level. Values are: `critical`: Indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging. `low`: Signifies that the battery is under the preferred threshold and should be charged soon. `good`: Denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging. `full`: Represents a battery that is fully charged, providing the maximum duration of usage.

Use a Get Device request to retrieve the current power status of a device. First, determine whether the device is wired. If the device is battery-powered (that is, not wired), get the battery level and status. Then, display the retrieved device power status in your app.

{% hint style="info" %} You can also use the prebuilt device details Seam Component, which includes a device power status display. {% endhint %}

{% tabs %} {% tab title="Python" %} Request:

device = seam.devices.get("36cf1a96-196d-41b0-9804-88154387f1f9")
if device.properties.has_direct_power == True:
  pprint("Power Source: Wired")
else:
  pprint("Power Source: Battery-powered")
  pprint("Battery Level: " + str(device.properties.battery.level))
  pprint("Battery Status: " + device.properties.battery.status)

Response:

'Power Source: Battery-powered'
'Battery Level: 0.9999532347993827'
'Battery Status: full'

{% endtab %}

{% tab title="cURL (bash)" %} Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/devices/get' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9"
}' | jq -r '"Power Source: " + 
  (if .device.properties.has_direct_power == true then "Wired" else "Battery-powered", 
  "Battery Level: " + (.device.properties.battery.level | tostring), 
  "Battery Status: " + .device.properties.battery.status end)'

Response:

Power Source: Battery-powered
Power Source: Battery Level: 0.9999532347993827
Power Source: Battery Status: full

{% endtab %}

{% tab title="JavaScript" %} Request:

const device = await seam.devices.get({device_id: "36cf1a96-196d-41b0-9804-88154387f1f9"});
if (device.properties.has_direct_power == true) {
  console.log("Power Source: Wired");
} else {
  console.log("Power Source: Battery-powered");
  console.log("Battery Level: " + device.properties.battery.level.toString());
  console.log("Battery Status: " + device.properties.battery.status);
}

Response:

Power Source: Battery-powered
Battery Level: 0.9999532347993827
Battery Status: full

{% endtab %}

{% tab title="Ruby" %} Request:

device = client.devices.get("36cf1a96-196d-41b0-9804-88154387f1f9")
if(device.properties['has_direct_power'] == true)
  puts "Power Source: Wired"
else
  puts "Power Source: Battery-powered"
  puts "Battery Level: " + device.properties['battery']['level'].to_s
  puts "Battery Status: " + device.properties['battery']['status']
end

Response:

Power Source: Battery-powered
Battery Level: 0.9999532347993827
Battery Status: full

{% endtab %}

{% tab title="PHP" %} Request:

$device = $seam->devices->get("36cf1a96-196d-41b0-9804-88154387f1f9");
if ($device->properties->has_direct_power === true) {
  echo "Power Source: Wired\n";
} else {
  echo "Power Source: Battery-powered\n";
  // echo "Battery Level: " + $device->properties->battery->level + "\n";
  echo "Battery Level: {$device->properties->battery->level}\n";
  echo "Battery Status: {$device->properties->battery->status}\n";
}

Response:

Power Source: Battery-powered
Battery Level: 0.99995323479938
Battery Status: full

{% endtab %}

{% tab title="C#" %} Request:

var device = seam.Devices.Get(deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9");
if (device.Properties.HasDirectPower == true)
{
  Console.WriteLine("Power Source: Wired");
} else {
  Console.WriteLine("Power Source: Battery-powered");
  if (device.Properties.Battery != null)
  {
    Console.WriteLine("Battery Level: " + device.Properties.Battery.Level);
    Console.WriteLine("Battery Status: " + device.Properties.Battery.Status);
  }
}

Response:

Power Source: Battery-powered
Battery Level: 0.9999532
Battery Status: Full

{% endtab %}

{% tab title="Java" %} Request:

Device device = seam.devices()
      .get(DevicesGetRequest.builder()
              .deviceId("36cf1a96-196d-41b0-9804-88154387f1f9")
              .build());
if (device.getProperties().getHasDirectPower() == true)
{
  System.out.println("Power Source: Wired");
} else {
  System.out.println("Power Source: Battery-powered");
  System.out.println("Battery Level: " + device.getProperties().getBattery().getLevel());
  System.out.println("Battery Status: " + device.getProperties().getBattery().getStatus());
}

Response:

Power Source: Battery-powered
Battery Level: 0.9999532
Battery Status: Full

{% endtab %}

{% tab title="Go" %} Request:

device, err := client.Devices.Get(
	context.Background(),
  &api.DevicesGetRequest{
    DeviceId: api.String("36cf1a96-196d-41b0-9804-88154387f1f9"),
  },
)
if err != nil {
	return err
}
fmt.Println("Online:", device.Properties.Online)
return nil

Response:

Online: true

{% endtab %} {% endtabs %}

Get Device Power Status Using Battery-Related Events

Seam generates the following battery-related events:

device.low_battery
device.battery_status_changed

You can retrieve these events using a List Events request or through webhooks and then display the corresponding status in your app.

Get Battery-Related Events Using a List Events Request

When issuing a List Events request to retrieve device.low_battery or device.battery_status_changed events for a specific device, include the following parameters:

Parameter	Type	Description
`device_id`	String (UUID)	ID of the device for which you want to retrieve `device.connected` or `device.disconnected` events
`event_type`	String	Event type that you want to retrieve, that is, `device.connected` or `device.disconnected`
`since`	String	Desired starting event generation date and time You must include `since` or `between`.
`between`	Set of two strings	Desired starting and ending event generation dates and times For example: `["2024-01-01T00:00:00Z", "2024-02-01T00:00:00Z"]` You must include `between` or `since`.

The following example uses the List Events request to retrieve all device.battery_status_changed events for a specific device since January 1, 2024:

{% tabs %} {% tab title="Python" %} Request:

device_battery_status_changed_events = seam.events.list(
    device_id = "36cf1a96-196d-41b0-9804-88154387f1f9",
    event_type = "device.battery_status_changed",
    since = "2024-01-01T00:00:00Z"
)
pprint(device_battery_status_changed_events)

Response:

[{'connected_account_id': 'c1413928-f527-4e12-abf9-d5e18d92dd33',
  'created_at': '2024-01-01T02:25:10.158Z',
  'device_id': '36cf1a96-196d-41b0-9804-88154387f1f9',
  'event_id': 'de4314a2-903d-53e9-bb5e-ded5d19ad074',
  'event_type': 'device.battery_status_changed',
  'occurred_at': '2024-01-01T02:25:10.158Z',
  'workspace_id': '398d80b7-3f96-47c2-b85a-6f8ba21d07be'}]

{% endtab %}

{% tab title="cURL (bash)" %} Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/devices/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type": "device.battery_status_changed",
  "since": "2024-01-01T00:00:00Z"
}'

Response:

{
  "events": [
    {
      "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.battery_status_changed",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-01-01T02:25:10.158Z",
      "occurred_at": "2024-01-01T02:25:10.158Z",
      "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
    }
  ],
  "ok": true
}

{% endtab %}

{% tab title="JavaScript" %} Request:

const device_battery_status_changed_events = await seam.events.list({
  device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
  event_type: "device.battery_status_changed",
  since: "2024-01-01T00:00:00Z"
})
console.log(device_battery_status_changed_events)

Response:

[
  {
    event_id: 'de4314a2-903d-53e9-bb5e-ded5d19ad074',
    device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
    event_type: 'device.battery_status_changed',
    workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
    created_at: '2024-01-01T02:25:10.158Z',
    occurred_at: '2024-01-01T02:25:10.158Z',
    connected_account_id: 'c1413928-f527-4e12-abf9-d5e18d92dd33'
  }
]

{% endtab %}

{% tab title="Ruby" %} Request:

device_battery_status_changed_events = client.events.list(
  device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
  event_type: "device.battery_status_changed",
  since: "2024-01-01T00:00:00Z"
)
puts device_battery_status_changed_events.inspect

Response:

[<Seam::Event:0x00438
  event_id="de4314a2-903d-53e9-bb5e-ded5d19ad074"
  device_id="36cf1a96-196d-41b0-9804-88154387f1f9"
  event_type="device.battery_status_changed"
  workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
  created_at=2024-01-01 02:25:10.158Z]

{% endtab %}

{% tab title="PHP" %} Request:

$device_battery_status_changed_events = $seam->events->list(
  device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
  event_type: "device.battery_status_changed",
  since: "2024-01-01T00:00:00Z"
);
echo json_encode($device_battery_status_changed_events), "\n";

Response:

{% code overflow="wrap" %}

[{"event_id":"de4314a2-903d-53e9-bb5e-ded5d19ad074","device_id":"36cf1a96-196d-41b0-9804-88154387f1f9","event_type":"device.battery_status_changed","workspace_id":"398d80b7-3f96-47c2-b85a-6f8ba21d07be","created_at":"2024-01-01T02:25:10.158Z","occurred_at":"2024-01-01T02:25:10.158Z"}]

{% endcode %} {% endtab %}

{% tab title="C#" %} Request:

var device_battery_status_changed_events = seam.Events.List(
    deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9",
    eventType: Seam.Api.Events.ListRequest.EventTypeEnum.DeviceBatteryStatusChanged,
    since: "2024-01-01T00:00:00Z"
);
foreach (var device_battery_status_changed_event in device_battery_status_changed_events)
{
  Console.WriteLine(device_battery_status_changed_event);
}

Response:

{
  "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
  "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type": "device.battery_status_changed",
  "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "created_at": "2024-01-01T02:25:10.158Z",
  "occurred_at": "2024-01-01T02:25:10.158Z"
}

{% endtab %}

{% tab title="Java" %} Request:

var deviceBatteryStatusChangedEvents = seam.events()
          .list(EventsListRequest.builder()
                  .deviceId("36cf1a96-196d-41b0-9804-88154387f1f9")
                  .eventType(EventsListRequestEventType.DEVICE_BATTERY_STATUS_CHANGED)
                  .since("2024-01-01T00:00:00Z")
                  .build());
System.out.println(deviceBatteryStatusChangedEvents);

Response:

[{
  "event_id" : "de4314a2-903d-53e9-bb5e-ded5d19ad074",
  "device_id" : "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type" : "device.battery_status_changed",
  "workspace_id" : "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "created_at" : "2024-01-01T02:25:10.158Z",
  "occurred_at" : "2024-01-01T02:25:10.158Z",
  "connected_account_id" : "c1413928-f527-4e12-abf9-d5e18d92dd33"
}]

{% endtab %}

{% tab title="Go" %} Request:

device_battery_status_changed_events, err := client.Events.List(
	context.Background(),
  &api.EventsListRequest{
    DeviceId: api.String("36cf1a96-196d-41b0-9804-88154387f1f9"),
    EventType: api.EventTypeBatteryStatusChanged.Ptr(),
    Since: api.String("2024-01-01T00:00:00Z"),
  },
)
if err != nil {
	return err
}
fmt.Println(device_battery_status_changed_events)
return nil

Response:

[{
  "event_id": "de4314a2-903d-53e9-bb5e-ded5d19ad074",
  "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type": "device.battery_status_changed",
  "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "created_at": "2024-01-01T02:25:10.158Z",
  "occurred_at": "2024-01-01T02:25:10.158Z",
  "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
}]

{% endtab %} {% endtabs %}

Retrieve Battery-Related Events Using a Webhook

You can set up webhook endpoints to receive device.battery_status_changed and device.low_battery events. Then, you can use the receipt of these events to display the corresponding device status in your app. For more information about configuring webhooks, see Webhooks.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

displaying-device-power-status.md

displaying-device-power-status.md

Displaying Device Power Status

Get Device Power Status Using Device Properties

Get Device Power Status Using Battery-Related Events

Get Battery-Related Events Using a List Events Request

Retrieve Battery-Related Events Using a Webhook

Files

displaying-device-power-status.md

Latest commit

History

displaying-device-power-status.md

File metadata and controls

Displaying Device Power Status

Get Device Power Status Using Device Properties

Get Device Power Status Using Battery-Related Events

Get Battery-Related Events Using a List Events Request

Retrieve Battery-Related Events Using a Webhook