Digital Inputs and Outputs

Digital inputs and outputs are used for communication between a robot and external devices or sensors by digital signals. Unlike analog signals, digital signals are binary, they can only be in one of two states: HIGH (1 / True) or LOW (0 / False). Digital inputs can only be read, while digital outputs can be read and written to.

Depending on the specific robot, a digital input or output may represent a physical pin on the robot cabinet or an abstract bit on a fieldbus.

Note

Interacting with Digital I/Os is currently only supported for robots within the Victor Robot Behavior Group.

Read and Write Digital Inputs and Outputs

A digital output is represented by a DigitalOutput object and a digital input by a DigitalInput object.

DigitalOutput

protocol DigitalOutput

Protocol to interact with digital outputs.

A digital output of a robot control is a readable and writable interface that is used for communication between a robot and external devices or sensors. Digital signals are binary, they can only be in one of two states: HIGH (True) or LOW (False).

Depending on the specific robot, a digital output may represent a physical pin on the robot cabinet or an abstract bit on a fieldbus.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod is_set()

Whether the digital pin is set to HIGH.

Return type:: bool

abstractmethod get_id()

Get the pin identifier for the represented pin.

Return type:: int

abstractmethod set()

Set the digital pin to HIGH.

Return type:: None

abstractmethod clear()

Set the digital pin to LOW.

Return type:: None

DigitalInput

protocol DigitalInput

Protocol to interact with digital inputs.

A digital input of a robot control is a readable interface that is used for communication between a robot and external devices or sensors. Digital signals are binary, they can only be in one of two states: HIGH (true) or LOW (false).

Depending on the specific robot, a digital input may represent a physical pin on the robot cabinet or an abstract bit on a fieldbus.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod is_set()

Whether the digital pin is set to HIGH.

Return type:: bool

abstractmethod get_id()

Get the pin identifier for the represented pin.

Return type:: int

They can be retrieved through the functions get_digital_input_v() and get_digital_output_v. Both functions require a numeric identifier which pin they should retrieve. The first pin has id 1.

A digital output pin can be set by calling the set() method on the pin object. In order to read the current value of digital output or digital input, use the is_set() method.

For a quick interaction it is possible to read, set and clear a digital output inline like this:

output_id = 1

robot.get_digital_output_v(output_id).set()

output_value = robot.get_digital_output_v(output_id).is_set()
_logger.info("Output '%s' has value '%s'", output_id, output_value)

robot.get_digital_output_v(output_id).clear()

Digital inputs can only be read but can be used in the same fashion.

If one input or output is used multiple times, the output object can be assigned to a variable and used without retrieving it multiple times.

output = robot.get_digital_output_v(1)

output.set()
_logger.info(
    "Output '%s' has value '%s'", output.get_id(), output.is_set()
)
output.clear()

Using Input and Output Groups

While single inputs and outputs often are sufficient enough control simple logic, most peripherals require setting more than one output or reading more than one input together.

voraus_robot_arm provides the DigitalInputGroup and DigitalOutputGroup to bundle multiple inputs and outputs in one convenient object.

DigitalOutputGroup

protocol DigitalOutputGroup

typing.Protocol.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod to_dict()

Read the latest values of all represented pins and return them as a dictionary mapping ids to values.

Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: dict[int, bool]

abstractmethod to_tuple()

Read the latest values of all represented pins and return them as a tuple of bools.

The order of values in the tuple matches to the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: tuple[bool, ...]

abstractmethod to_int()

Read the latest values of all represented pins and return them as a single base 10 integer.

The least significant bit is read from the pin with the lowest id, while the highest significant bit is read from the pin with the highest id. Bits in between are in increasing id order.

Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1.

Example: If the group represents the ids 1, 2, and 4 with the values False, True and True the returned value is 6. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: int

abstractmethod get_ids()

Get the pin identifiers for all represented pins of this group.

Return type:: tuple[int, ...]

abstractmethod set_from_dict(to)

Set the pins of this group to the values within the provided dict.

Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (dict[int, bool]) – The states of the pins to be set. The keys of the dicts are the pin ids, the values are the desired pin state. All pin ids within the dict must be member of the pin group. Setting only a subset of pins of the group is supported.
Raises:: ValueError – If one or more pin ids are not member of this pin group
Return type:: None

abstractmethod set_from_tuple(to)

Set the pins of this group via a tuple.

The order of values in the to argument has to match the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (tuple[bool, ...]) – The states of the pins to be set. All pins of the group must be set.
Return type:: None

abstractmethod set_from_int(to)

Set the all represented pins based on a single base 10 integer.

Note that it depends on the robot control in use whether the values are set at once or sequential.

Parameters:: to (int) – The base 10 integer that represent the bits to set the pins of this group. The least significant bit is set to the pin with the lowest id, while the highest significant bit is set to the pin with the highest id. Bits in between are in increasing id order. Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1. Example: If the group represents the ids 1, 2, and 4 and should be set to the values False, True and True correct value is 6.
Return type:: None

DigitalInputGroup

protocol DigitalInputGroup

typing.Protocol.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod to_dict()

Read the latest values of all represented pins and return them as a dictionary mapping ids to values.

Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: dict[int, bool]

abstractmethod to_tuple()

Read the latest values of all represented pins and return them as a tuple of bools.

The order of values in the tuple matches to the same order of ids retrievable with get_ids. Note that it depends on the robot control in use whether the values are read at once or sequential.

Return type:: tuple[bool, ...]

abstractmethod to_int()

Read the latest values of all represented pins and return them as a single base 10 integer.

The least significant bit is read from the pin with the lowest id, while the highest significant bit is read from the pin with the highest id. Bits in between are in increasing id order.

Please note, that gaps in ids do not jump binary increments and the maximum number returned is 2^len(get_ids)-1.

Return type:: int

abstractmethod get_ids()

Get the pin identifiers for all represented pins of this group.

Return type:: tuple[int, ...]

They can be retrieved through the functions get_digital_input_group_v() and get_digital_output_group_v. Similar to their non group counterparts the methods require a list of numeric identifiers which inputs or outputs they should control.

The current values of the whole group can then be read and returned in different data styles with to_dict(), to_tuple() and to_int() methods.

Similarly, all inputs can be set from the same data types with the methods set_from_dict(), set_from_tuple() and set_from_int().

Please note that the control of a group is not exclusive and single inputs and outputs can still be set as normally. It is also possible to share outputs and inputs between multiple groups. Also note, that it depends on the robot control in use whether the values of a group are read and written at once or sequential.

The following example shows how multiple conveyors connected to digital outputs 1,2 and 4 could be activated and deactivated:

conveyors = robot.get_digital_output_group_v((1, 2, 4))

on = {1: True, 2: False, 4: True}
off = {1: False, 2: False, 4: False}

conveyors.set_from_dict(on)

_logger.info("Conveyors have the state %s", conveyors.to_tuple())

conveyors.set_from_dict(off)

Full Example

The following example shows a simple interaction with digital inputs and outputs:

Working with digital inputs and outputs example

"""IO example for robots with Victor behavior."""

from logging import Logger, getLogger
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    DigitalInputVictorTrait,
    DigitalOutputVictorTrait,
    VorausIndustrialRobotArm,
    configure_logging,
)

_logger: Logger = getLogger(__name__)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401


@runtime_checkable
class _RequiredRobotTraits(
    DigitalOutputVictorTrait, DigitalInputVictorTrait, Protocol
): ...


def run_inline(robot: _RequiredRobotTraits) -> None:
    """Show how IOs can be used inline."""
    output_id = 1

    robot.get_digital_output_v(output_id).set()

    output_value = robot.get_digital_output_v(output_id).is_set()
    _logger.info("Output '%s' has value '%s'", output_id, output_value)

    robot.get_digital_output_v(output_id).clear()


def run_use_object(robot: _RequiredRobotTraits) -> None:
    """Show how IOs can be used with handles."""
    output = robot.get_digital_output_v(1)

    output.set()
    _logger.info(
        "Output '%s' has value '%s'", output.get_id(), output.is_set()
    )
    output.clear()


def run_group_example(robot: _RequiredRobotTraits) -> None:
    """Show how IOs can be grouped."""
    conveyors = robot.get_digital_output_group_v((1, 2, 4))

    on = {1: True, 2: False, 4: True}
    off = {1: False, 2: False, 4: False}

    conveyors.set_from_dict(on)

    _logger.info("Conveyors have the state %s", conveyors.to_tuple())

    conveyors.set_from_dict(off)


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    with robot.connect(host=VORAUS_CORE_HOST, port=VORAUS_CORE_PORT):
        run_inline(robot)
        run_use_object(robot)
        run_group_example(robot)

Definition of the Digital Input and Output Methods

The digital input related functionality is defined in the DigitalInputVictorTrait:

DigitalInputVictorTrait

protocol DigitalInputVictorTrait

Trait to read digital inputs for a robot with Victor behavior.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod get_digital_input_v(id)

Get a digital input handle.

Parameters:: id (int) – The id of the digital input to handle.
Return type:: DigitalInput
Returns:: A handle to the digital input.

abstractmethod get_digital_input_group_v(ids)

Get a group handle for digital inputs.

Parameters:: ids (tuple[int, ...]) – A tuple of input ids to handle as a group. IDs must be in increasing order.
Return type:: DigitalInputGroup
Returns:: A handle to the digital inputs.

abstractmethod get_maximum_input_id()

Get maximum id which can be read with the current robot.

Return type:: int

The digital input related functionality is defined in the DigitalOutputVictorTrait:

DigitalOutputVictorTrait

protocol DigitalOutputVictorTrait

Implementation of a trait to read and write digital outputs and outputs for a robot with Victor behavior.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod get_digital_output_v(id)

Get a digital output handle.

Parameters:: id (int) – The id of the digital output to handle.
Return type:: DigitalOutput
Returns:: A handle to the digital output.

abstractmethod get_digital_output_group_v(ids)

Get a group handle for digital outputs.

Parameters:: ids (tuple[int, ...]) – A tuple of output ids to handle as a group. IDs must be in increasing order.
Return type:: DigitalOutputGroup
Returns:: A handle to the digital outputs.

abstractmethod get_maximum_output_id()

Get maximum id which can be read with the current robot.

Return type:: int

Tools

Telemetry