roboto.domain.device_types#

Device types: named kinds of device within an organization, such as one robot model.

A device has at most one device type, whose ID is in device_type_id.

Submodules#

Package Contents#

class roboto.domain.device_types.CreateDeviceTypeRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for POST /v1/device-types/create, which creates a device type in the caller’s org.

Parameters:: data (Any)

description: str | None = None#: Free-text description of the device type.

metadata: dict[str, Any]#: Initial key-value metadata pairs to associate with the device type.

name: str#: Name of the device type, unique within the org.

tags: list[str]#: Initial tags to associate with the device type.

class roboto.domain.device_types.DeviceType(record, roboto_client=None)#

A named kind of device within an organization, such as one robot model.

A Device has at most one device type, whose ID is its device_type_id. A device type has its own configurations (configurations), such as a URDF or a bill of materials that applies to every device of that type, and its own description, metadata and tags. Devices inherit none of the type’s description, metadata or tags. A device’s configurations listed with include_inherited=True (list_files()) include its type’s configurations beside its own.

Device type IDs (dt_...) are assigned by Roboto; the name is user-provided and unique within the org.

Note

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

Examples

Give every device of a type the same URDF, then read it back from one device:

>>> import pathlib
>>> from roboto import Device, DeviceType
>>> device_type = DeviceType.create(name="mk2", description="Second-generation arm")
>>> device_type.configurations.upload_file(pathlib.Path("/path/to/mk2.urdf"), "mk2.urdf")
>>> device = Device.from_id("robot_001").set_device_type(device_type.device_type_id)
>>> for file in device.configurations.list_files(include_inherited=True):
...     print(file.relative_path, file.association.is_device_type)
mk2.urdf True

Parameters:

record (roboto.domain.device_types.record.DeviceTypeRecord)
roboto_client (Optional[roboto.http.RobotoClient])

property configurations: roboto.domain.files.FileSystem#

Files that apply to every device of the type, such as a URDF.

Return type:: roboto.domain.files.FileSystem

classmethod create(name, description=None, metadata=None, tags=None, caller_org_id=None, roboto_client=None)#

Create a device type in an organization.

Parameters:

name (str) – Name of the device type, unique within the organization.
description (Optional[str]) – Optional free-text description of the device type.
metadata (Optional[dict[str, Any]]) – Optional key-value pairs to associate with the device type.
tags (Optional[list[str]]) – Optional tags to associate with the device type.
caller_org_id (Optional[str]) – The organization to create the device type in. 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:

The newly created device type.

Raises:

RobotoConflictException – The organization already has a device type with this name.
RobotoFeatureNotAvailableException – Device types are not enabled for the organization.
RobotoUnauthorizedException – The caller lacks permission to manage devices in the organization.

Return type:

DeviceType

Examples

>>> device_type = DeviceType.create(name="mk2", description="Second-generation arm", tags=["arm"])
>>> device_type.device_type_id
'dt_abc123'

property created: datetime.datetime#

The timestamp when this device type was created.

Return type:: datetime.datetime

property created_by: str#

The user ID of the person who created this device type.

Return type:: str

delete()#

Delete this device type.

Refused while any device is of this type; reassign or clear those devices’ types first. The device type’s configurations (configurations) are deleted with it, every version of each file, shortly after this call returns. Links elsewhere that point at those files stop working. Deleting a device type that no longer exists succeeds.

Raises:

RobotoConflictException – At least one device is of this type.
RobotoFeatureNotAvailableException – Device types are not enabled for the organization.
RobotoUnauthorizedException – The caller lacks permission to delete this device type.

Return type:

None

Examples

>>> device_type = DeviceType.from_id("dt_abc123")
>>> device_type.delete()

property description: str | None#

Free-text description of this device type.

Return type:: Optional[str]

property device_count: int#

Number of devices of this device type, counted when Roboto returned this device type.

The count does not follow devices added or removed later; call from_id() for a current count.

Return type:: int

property device_type_id: str#

This device type’s Roboto-assigned dt_ ID, unique across all orgs and never changed.

Return type:: str

devices()#

List the devices that are of this device type, newest first.

Yields:

Each device of this type, fetched a page at a time.

Raises:

RobotoFeatureNotAvailableException – Device types are not enabled for the organization.
RobotoUnauthorizedException – The caller lacks permission to view this device type, or to manage devices in its org.

Return type:

collections.abc.Generator[roboto.domain.devices.Device, None, None]

Examples

>>> device_type = DeviceType.from_id("dt_abc123")
>>> for device in device_type.devices():
...     print(device.device_id)
robot_002
robot_001

classmethod for_org(org_id, roboto_client=None)#

List an organization’s device types, newest first.

Parameters:

org_id (str) – The organization ID to list device types for.
roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient instance for API communication. If not provided, the default client configuration will be used.

Yields:

Each of the organization’s device types, fetched a page at a time.

Raises:

RobotoFeatureNotAvailableException – Device types are not enabled for the organization.
RobotoUnauthorizedException – The caller lacks permission to manage devices in the organization.

Return type:

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

Examples

>>> for device_type in DeviceType.for_org("og_abc123"):
...     print(device_type.name)
mk3
mk2

classmethod from_id(device_type_id, roboto_client=None, org_id=None)#

Retrieve a device type by its ID.

Parameters:

device_type_id (str) – The Roboto-assigned dt_ ID of the device type, not its name.
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 that owns the device type. 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:

The device type.

Raises:

RobotoFeatureNotAvailableException – Device types are not enabled for the organization.
RobotoNotFoundException – The organization has no device type with this ID.
RobotoUnauthorizedException – The caller lacks permission to view the device type.

Return type:

DeviceType

Examples

>>> device_type = DeviceType.from_id("dt_abc123", org_id="og_abc123")
>>> device_type.name
'mk2'

property metadata: dict[str, Any]#

Key-value metadata pairs associated with this device type.

Return type:: dict[str, Any]

property modified: datetime.datetime#

The timestamp when this device type was last modified.

Return type:: datetime.datetime

property modified_by: str#

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

Return type:: str

property name: str#

This device type’s name, unique within its org.

Return type:: str

property org_id: str#

The ID of the org to which this device type belongs.

Return type:: str

property record: roboto.domain.device_types.record.DeviceTypeRecord#

Underlying DeviceTypeRecord for this device type.

This is the raw record as returned by Roboto and may evolve over time; prefer the public DeviceType API unless you need direct access to the record.

Return type:: roboto.domain.device_types.record.DeviceTypeRecord

property tags: list[str]#

List of tags associated with this device type.

Return type:: list[str]

update(request)#

Update this device type’s name, description, metadata or tags.

Parameters:

request (roboto.domain.device_types.operations.UpdateDeviceTypeRequest) – The changes to apply. Fields left at their defaults change nothing.

Returns:

Updated DeviceType instance with the changes applied.

Raises:

RobotoConflictException – The new name is already taken by another device type in the org.
RobotoFeatureNotAvailableException – Device types are not enabled for the organization.
RobotoUnauthorizedException – The caller lacks permission to edit this device type.

Return type:

DeviceType

Examples

Rename a device type and clear its description:

>>> from roboto import UpdateDeviceTypeRequest
>>> device_type = DeviceType.from_id("dt_abc123")
>>> device_type = device_type.update(UpdateDeviceTypeRequest(name="mk2-rev-b", description=None))

class roboto.domain.device_types.DeviceTypeRecord(/, **data)#

Bases: pydantic.BaseModel

A device type as returned by Roboto.

Parameters:: data (Any)

created: datetime.datetime#: Date/time when this device type was created.

created_by: str#: The user who created this device type.

description: str | None = None#: Free-text description of this device type.

device_count: int#: Number of devices of this device type, counted when Roboto returned this record.

device_type_id: str#: A Roboto-assigned identifier for this device type (dt_...), unique across all orgs and never changed.

metadata: dict[str, Any]#: Key-value metadata pairs associated with this device type.

modified: datetime.datetime#: Date/time when this device type was last modified.

modified_by: str#: The user who last modified this device type.

name: str#: A user-provided name for this device type, unique within its org.

org_id: str#: The org to which this device type belongs.

tags: list[str]#: List of tags associated with this device type.

class roboto.domain.device_types.UpdateDeviceTypeRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for PUT /v1/device-types/id/<device_type_id>.

Fields left at their defaults change nothing.

Parameters:: data (Any)

description: str | roboto.sentinels.NotSetType | None#: New description. None clears it.

metadata_changeset: roboto.updates.MetadataChangeset | None = None#: Metadata fields and tags to add, change, or remove.

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | roboto.sentinels.NotSetType#: New name for the device type, unique within its org. Cannot be cleared.