roboto.domain.devices.device#

Module Contents#

class roboto.domain.devices.device.Device(record, roboto_client=None)#

A device is a non-human entity that can interact with Roboto on behalf of an organization.

Devices represent robots, systems, or other non-human entities that need to authenticate and interact with the Roboto platform. Each device is uniquely identified by a device_id within its organization and can be assigned API tokens for secure authentication.

Common device types include:

  • Robots that upload log data directly from their onboard software

  • Automated upload stations that collect and transmit data from multiple sources

  • Edge computing devices that process and forward data to Roboto

Devices are associated with Org entities and can create Token objects for authentication. The underlying data is stored in DeviceRecord objects for wire transmission.

Device IDs are typically meaningful identifiers like serial numbers, asset tags, or other organization-specific naming schemes that help identify the physical or logical entity in the real world.

Note

Devices cannot be instantiated directly through the constructor. Use the class methods create(), from_id(), or for_org() to obtain Device instances.

Parameters:
classmethod create(device_id, caller_org_id=None, roboto_client=None)#

Register a new device with the Roboto platform.

Creates a new device entity that can authenticate and interact with Roboto on behalf of the specified organization. The device_id must be unique within the organization.

Parameters:

  • device_id (str) – A user-provided identifier for the device, unique within the organization. This is typically a meaningful identifier like a serial number, asset tag, or other organization-specific naming scheme.

  • caller_org_id (Optional[str]) – The organization ID to register the device under. If not specified and the caller belongs to only one organization, that organization will be used. Required if the caller belongs to multiple organizations.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient instance for API communication. If not provided, the default client configuration will be used.

Returns:

A Device instance representing the newly registered device.

Raises:
Return type:

Device

Examples

Register a robot device:

>>> device = Device.create(
...     device_id="robot_001",
...     caller_org_id="og_abc123"
... )
>>> print(f"Registered device: {device.device_id}")
Registered device: robot_001

Register an upload station:

>>> device = Device.create(device_id="upload_station_alpha")
>>> print(f"Device org: {device.org_id}")
Device org: og_xyz789
create_token(expiry_days=366, name=None, description=None)#

Create an authentication token for this device.

Generates a new API token that can be used to authenticate requests made on behalf of this device. The token secret is returned only once and cannot be retrieved again, so it must be stored securely by the caller.

Parameters:

  • expiry_days (int) – Number of days until the token expires. Defaults to 366 days (1 year). Must be a positive integer.

  • name (Optional[str]) – Human-readable name for the token. If not provided, defaults to “{org_id}_{device_id}” format.

  • description (Optional[str]) – Optional description explaining the token’s purpose or usage context.

Returns:

  • Token: The Token object representing the created token

  • str: The secret token value (only available at creation time)

Return type:

A tuple containing

Raises:

  • RobotoDomainException – If token creation fails or the secret is not returned by the server (this should never happen under normal circumstances).

  • RobotoUnauthorizedException – If the caller lacks permission to create tokens for this device.

Examples

Create a token with default settings:

>>> device = Device.from_id("robot_001", org_id="og_abc123")
>>> token, secret = device.create_token()
>>> print(f"Token created: {token.token_id}")
>>> print(f"Secret (save this!): {secret}")
Token created: to_abc123def456
Secret (save this!): robo_pat_abc123def456...

Create a token with custom expiry and description:

>>> token, secret = device.create_token(
...     expiry_days=30,
...     name="Monthly Upload Token",
...     description="Token for automated monthly data uploads"
... )
>>> print(f"Token expires in 30 days: {token.token_id}")
Token expires in 30 days: to_def789ghi012
property created: datetime.datetime#

The timestamp when this device was registered with Roboto.

Return type:

datetime.datetime

property created_by: str#

The user ID of the person who registered this device.

Return type:

str

delete()#

Delete this device from the Roboto platform.

Permanently removes this device and all associated tokens. This action cannot be undone. Any tokens created for this device will be immediately invalidated.

Raises:
Return type:

None

Examples

Delete a device after confirming its identity:

>>> device = Device.from_id("old_robot_001")
>>> print(f"Deleting device: {device.device_id}")
>>> device.delete()
>>> print("Device deleted successfully")
Deleting device: old_robot_001
Device deleted successfully
property device_id: str#

This device’s ID. Device ID is a user-provided identifier for a device, which is unique within the device’s org.

Return type:

str

classmethod for_org(org_id, roboto_client=None)#

List all devices registered for a given organization.

Retrieves all devices that belong to the specified organization. For organizations with large numbers of devices, this method uses pagination and yields results as they become available from the API.

Parameters:

  • org_id (str) – The organization ID to list devices for.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient instance for API communication. If not provided, the default client configuration will be used.

Returns:

A generator of Device objects. For organizations with many devices, this may involve multiple service calls, and the generator will yield results as they become available.

Raises:
Return type:

collections.abc.Generator[Device, None, None]

Examples

List all devices in an organization:

>>> for device in Device.for_org("og_abc123"):
...     print(f"Device: {device.device_id} (created: {device.created})")
Device: robot_001 (created: 2024-01-15 10:30:00)
Device: upload_station_beta (created: 2024-01-17 09:15:00)

Count devices in an organization:

>>> device_count = sum(1 for _ in Device.for_org("og_abc123"))
>>> print(f"Total devices: {device_count}")
Total devices: 2
classmethod from_id(device_id, roboto_client=None, org_id=None)#

Retrieve a device by its device ID.

Looks up and returns a Device instance for the specified device_id. The device_id must be unique within the organization scope.

Parameters:

  • device_id (str) – The device ID to look up. This is the user-provided identifier that was specified when the device was created.

  • roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient instance for API communication. If not provided, the default client configuration will be used.

  • org_id (Optional[str]) – The organization ID that owns the device. If not specified and the caller belongs to only one organization, that organization will be used. Required if the caller belongs to multiple organizations.

Returns:

A Device object representing the specified device.

Raises:
Return type:

Device

Examples

Retrieve a device by ID with explicit organization:

>>> device = Device.from_id("robot_001", org_id="og_abc123")
>>> print(f"Device: {device.device_id} in org {device.org_id}")
Device: robot_001 in org og_abc123

Retrieve a device:

>>> device = Device.from_id("upload_station_alpha")
>>> print(f"Found device created by: {device.created_by}")
Found device created by: user@example.com
property modified: datetime.datetime#

The timestamp when this device record was last modified.

Return type:

datetime.datetime

property modified_by: str#

The user ID of the person who last modified this device record.

Return type:

str

property org_id: str#

The ID of the org to which this device belongs.

Return type:

str

property record: roboto.domain.devices.record.DeviceRecord#

The underlying DeviceRecord object which represents this device. This is often used as the wire representation of a device during API requests, and is subject to evolve over time. You should not program against this if avoidable.

Return type:

roboto.domain.devices.record.DeviceRecord

tokens()#

Retrieve all authentication tokens associated with this device.

Returns a list of all tokens that have been created for this device, including both active and expired tokens. The token secrets are not included in the response as they are only available at creation time.

Returns:

A sequence of Token objects representing all tokens created for this device. The sequence may be empty if no tokens have been created.

Raises:

RobotoUnauthorizedException – If the caller lacks permission to list tokens for this device.

Return type:

collections.abc.Sequence[roboto.domain.tokens.Token]

Examples

List all tokens for a device:

>>> device = Device.from_id("robot_001")
>>> tokens = device.tokens()
>>> for token in tokens:
...     print(f"Token: {token.token_id}")
Token: to_abc123def456
Token: to_ghi789jkl012

Check if device has any tokens:

>>> device = Device.from_id("new_robot")
>>> if device.tokens():
...     print("Device has tokens")
... else:
...     print("No tokens found for device")
No tokens found for device
On this page