j5.components package

Module contents

This module contains components, which are the smallest logical element of hardware.

class j5.components.BatterySensor(identifier: int, backend: j5.components.battery_sensor.BatterySensorInterface)[source]

Bases: j5.components.component.Component

A sensor capable of monitoring a battery.

current

Get the current of the battery sensor.

Returns:current measured by the sensor.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.battery_sensor.BatterySensorInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
voltage

Get the voltage reported by the battery sensor.

Returns:voltage measured by the sensor.
class j5.components.BatterySensorInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to read data from a BatterySensor.

get_battery_sensor_current(identifier: int) → float[source]

Get the current of a battery sensor.

Parameters:identifier – Identifier of battery sensor.
Returns:current measured by the sensor.
get_battery_sensor_voltage(identifier: int) → float[source]

Get the voltage of a battery sensor.

Parameters:identifier – Identifier of battery sensor.
Returns:voltage measured by the sensor.
class j5.components.Button(identifier: int, backend: j5.components.button.ButtonInterface)[source]

Bases: j5.components.component.Component

A button.

identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.button.ButtonInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
is_pressed

Get the current pushed state of the button.

Returns:current pushed state of the button.
wait_until_pressed() → None[source]

Halt the program until this button is pushed.

class j5.components.ButtonInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required for a button.

get_button_state(identifier: int) → bool[source]

Get the state of a button.

Parameters:identifier – Button identifier to fetch state of.
Returns:state of the button.
wait_until_button_pressed(identifier: int) → None[source]

Halt the program until this button is pushed.

Parameters:identifier – Button identifier to wait for.
class j5.components.Component[source]

Bases: object

A component is the smallest logical part of some hardware.

identifier

An integer to identify the component on a board.

classmethod interface_class() → Type[j5.components.component.Interface][source]

Get the interface class that is required to use this component.

class j5.components.DerivedComponent[source]

Bases: j5.components.component.Component

A derived component is a component that can take another component as a parameter.

For example, a device may be attached to various pins on the board, and this could vary depending on what the user wants. We solve this by passing the pins to the derived component.

>>> u = Ultrasound(pin_0, pin_1)
identifier

An integer to identify the component on a board.

Raises:NotSupportedByComponentError – derived components have no id.
static interface_class() → Type[j5.components.component.Interface][source]

Get the interface class that is required to use this component.

Returns:interface class.
class j5.components.GPIOPin(identifier: int, backend: j5.components.gpio_pin.GPIOPinInterface, *, initial_mode: Union[Type[j5.components.component.DerivedComponent], j5.components.gpio_pin.GPIOPinMode], hardware_modes: Set[j5.components.gpio_pin.GPIOPinMode] = {<GPIOPinMode.DIGITAL_OUTPUT: 3>}, firmware_modes: Set[Type[j5.components.component.DerivedComponent]] = {})[source]

Bases: j5.components.component.Component

A GPIO Pin.

DEFAULT_FW_MODE = {}
DEFAULT_HW_MODE = {<GPIOPinMode.DIGITAL_OUTPUT: 3>}
analogue_read() → float[source]

Get the scaled analogue reading of the pin.

Returns:scaled analogue reading
analogue_write(new_value: float) → None[source]

Set the analogue value of the pin.

Parameters:new_value – analogue value
Raises:ValueError – pin value must be between 0 and 1
digital_read() → bool[source]

Get the digital state of the pin.

Returns:digital read state of the pin.
digital_write(state: bool) → None[source]

Set the digital state of the pin.

Parameters:state – digital state.
firmware_modes

Get the supported firmware modes.

Returns:supported firmware modes.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.gpio_pin.GPIOPinInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
last_digital_write

Get the last set digital state of the pin.

This does not perform a read operation, it only gets the last set value, which is usually cached in memory.

Returns:last set digital state of the pin
mode

Get the mode of this pin.

Returns:current mode of the pin.
pwm_write(new_value: float) → None[source]

Set the PWM value of the pin.

Parameters:new_value – new duty cycle
Raises:ValueError – pin value must be between 0 and 1
class j5.components.GPIOPinInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required for a GPIO Pin.

get_gpio_pin_digital_state(identifier: int) → bool[source]

Get the last written state of the GPIO pin.

Parameters:identifier – pin number
Returns:Last known digital state of the pin.
get_gpio_pin_mode(identifier: int) → j5.components.gpio_pin.GPIOPinMode[source]

Get the hardware mode of a GPIO pin.

Parameters:identifier – pin number.
Returns:mode of the pin.
read_gpio_pin_analogue_value(identifier: int) → float[source]

Read the scaled analogue value of the GPIO pin.

Parameters:identifier – pin number
Returns:scaled analogue value of the pin.
read_gpio_pin_digital_state(identifier: int) → bool[source]

Read the digital state of the GPIO pin.

Parameters:identifier – pin number
Returns:digital state of the pin.
set_gpio_pin_mode(identifier: int, pin_mode: j5.components.gpio_pin.GPIOPinMode) → None[source]

Set the hardware mode of a GPIO pin.

Parameters:
  • identifier – pin number to set.
  • pin_mode – mode to set the pin to.
write_gpio_pin_dac_value(identifier: int, scaled_value: float) → None[source]

Write a scaled analogue value to the DAC on the GPIO pin.

Parameters:
  • identifier – pin number
  • scaled_value – scaled analogue value to write
write_gpio_pin_digital_state(identifier: int, state: bool) → None[source]

Write to the digital state of a GPIO pin.

Parameters:
  • identifier – pin number
  • state – desired digital state.
write_gpio_pin_pwm_value(identifier: int, duty_cycle: float) → None[source]

Write a scaled analogue value to the PWM on the GPIO pin.

Parameters:
  • identifier – pin number
  • duty_cycle – duty cycle to writee
class j5.components.GPIOPinMode[source]

Bases: enum.IntEnum

Hardware modes that a GPIO pin can be set to.

ANALOGUE_INPUT = 4

The analogue voltage of the pin can be read.

ANALOGUE_OUTPUT = 5

The analogue voltage of the pin can be set using a DAC.

DIGITAL_INPUT = 0

The digital state of the pin can be read

DIGITAL_INPUT_PULLDOWN = 2

Same as DIGITAL_INPUT but internal pull-down is enabled

DIGITAL_INPUT_PULLUP = 1

Same as DIGITAL_INPUT but internal pull-up is enabled

DIGITAL_OUTPUT = 3

The digital state of the pin can be set.

PWM_OUTPUT = 6

A PWM output signal can be created on the pin.

class j5.components.Interface[source]

Bases: object

A base class for interfaces to inherit from.

class j5.components.LED(identifier: int, backend: j5.components.led.LEDInterface)[source]

Bases: j5.components.component.Component

A standard Light Emitting Diode.

identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.led.LEDInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
state

Get the current state of the LED.

Returns:current state of the LED.
class j5.components.LEDInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control an LED.

get_led_state(identifier: int) → bool[source]

Get the state of an LED.

Parameters:identifier – identifier of the LED.
Returns:current state of the LED.
set_led_state(identifier: int, state: bool) → None[source]

Set the state of an LED.

Parameters:
  • identifier – identifier of the LED.
  • state – desired state of the LED.
class j5.components.Motor(identifier: int, backend: j5.components.motor.MotorInterface)[source]

Bases: j5.components.component.Component

Brushed DC motor output.

identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.component.Interface][source]

Get the interface class that is required to use this component.

Returns:interface class.
power

Get the current power of this output.

Returns:current power of this output.
class j5.components.MotorInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control a motor board.

get_motor_state(identifier: int) → Union[float, j5.components.motor.MotorSpecialState][source]

Get the current motor state.

Parameters:identifier – identifier of the motor
Returns:state of the motor.
set_motor_state(identifier: int, power: Union[float, j5.components.motor.MotorSpecialState]) → None[source]

Set the state of a motor.

Parameters:
  • identifier – identifier of the motor
  • power – state of the motor.
class j5.components.MotorSpecialState[source]

Bases: enum.Enum

An enum of the special states that a motor can be set to.

BRAKE = 1
COAST = 0
exception j5.components.NotSupportedByComponentError[source]

Bases: Exception

This is thrown when hardware does not support the action that is attempted.

class j5.components.Piezo(identifier: int, backend: j5.components.piezo.PiezoInterface)[source]

Bases: j5.components.component.Component

A standard piezo.

buzz(duration: Union[int, float, datetime.timedelta], pitch: Union[int, float, j5.components.piezo.Note]) → None[source]

Queue a note to be played.

Float and integer durations are measured in seconds.

Parameters:
  • duration – length to play for:
  • pitch – pitch of buzz.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.piezo.PiezoInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
static verify_duration(duration: datetime.timedelta) → None[source]

Verify that a duration is valid.

Parameters:

duration – duration to validate.

Raises:
static verify_pitch(pitch: Union[int, float, j5.components.piezo.Note]) → None[source]

Verify that a pitch is valid.

Parameters:

pitch – pitch to validate.

Raises:
class j5.components.PiezoInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control an piezo.

buzz(identifier: int, duration: datetime.timedelta, frequency: float) → None[source]

Queue a pitch to be played.

Parameters:
  • identifier – piezo identifier to play pitch on.
  • duration – duration of the tone.
  • frequency – Pitch of the tone in Hz.
class j5.components.PowerOutput(identifier: int, backend: j5.components.power_output.PowerOutputInterface)[source]

Bases: j5.components.component.Component

A power output channel.

It can be enabled/disabled, and the current being drawn on this channel can be measured.

current

Get the current being drawn on this power output, in amperes.

Returns:current being drawn on this power output, in amperes.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.power_output.PowerOutputInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
is_enabled

Get whether the output is enabled.

Returns:output enabled
class j5.components.PowerOutputInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control a power output channel.

get_power_output_current(identifier: int) → float[source]

Get the current being drawn on a power output, in amperes.

Parameters:identifier – power output to fetch current of.
Returns:current of the output.
get_power_output_enabled(identifier: int) → bool[source]

Get whether a power output is enabled.

Parameters:identifier – power output to fetch status of.
Returns:status of the power output.
set_power_output_enabled(identifier: int, enabled: bool) → None[source]

Set whether a power output is enabled.

Parameters:
  • identifier – power output to enable / disable
  • enabled – status of the power output.
class j5.components.PowerOutputGroup(outputs: Mapping[T, j5.components.power_output.PowerOutput])[source]

Bases: object

A group of PowerOutputs.

power_off() → None[source]

Disable all outputs in the group.

power_on() → None[source]

Enable all outputs in the group.

class j5.components.PWMLED(identifier: int, backend: j5.components.pwm_led.PWMLEDInterface)[source]

Bases: j5.components.component.Component

A Light Emitting Diode, driven by a PWM output.

This usually means that the LED is of variable brightness.

duty_cycle

Get the current duty cycle of the LED.

Returns:current duty cycle of the LED.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.pwm_led.PWMLEDInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
class j5.components.PWMLEDInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control a PWM LED.

get_pwm_led_duty_cycle(identifier: int) → float[source]

Get the duty cycle of an LED.

Parameters:identifier – identifier of the PWM LED.
Returns:current duty cycle of the LED.
set_pwm_led_duty_cycle(identifier: int, duty_cycle: float) → None[source]

Set the duty cycle of an LED.

Parameters:
  • identifier – identifier of the PWM LED.
  • duty_cycle – desired duty cycle of the LED.
class j5.components.RGBColour[source]

Bases: enum.Enum

The colour channels on an RGB LED.

BLUE = 'blue'
GREEN = 'green'
RED = 'red'
class j5.components.RGBLED(identifier: int, backend: j5.components.rgb_led.RGBLEDInterface)[source]

Bases: j5.components.component.Component

A Light Emitting Diode, driven by a PWM output.

This usually means that the LED is of variable brightness.

blue

Get the current value of the blue channel.

Returns:current duty cycle of the blue channel.
get_channel(channel: Union[str, j5.components.rgb_led.RGBColour]) → float[source]

Get the current value of a channel.

Parameters:channel – The channel to get the value for.
Returns:The duty cycle for the channel.
Raises:ValueError – channel is not a valid RGB channel.
green

Get the current value of the green channel.

Returns:current duty cycle of the green channel.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.rgb_led.RGBLEDInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
red

Get the current value of the red channel.

Returns:current duty cycle of the red channel.
rgb

Get a tuple of the channel duty cycles.

Returns:tuple of duty cycles (R, G, B).
set_channel(channel: Union[str, j5.components.rgb_led.RGBColour], duty_cycle: float) → None[source]

Set the current value of a channel.

Parameters:
  • channel – The channel to get the value for.
  • duty_cycle – The duty cycle to set the channel to.
Raises:
  • ValueError – channel is not a valid RGB channel.
  • ValueError – duty cycle is not in expected range.
class j5.components.RGBLEDInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control a RGB LED.

get_rgb_led_channel_duty_cycle(identifier: int, channel: j5.components.rgb_led.RGBColour) → float[source]

Get the duty cycle of a channel on the LED.

Parameters:
  • identifier – identifier of the RGB LED.
  • channel – channel to get the duty cycle for.
Returns:

current duty cycle of the LED.

set_rgb_led_channel_duty_cycle(identifier: int, channel: j5.components.rgb_led.RGBColour, duty_cycle: float) → None[source]

Set the duty cycle of a channel on the LED.

Parameters:
  • identifier – identifier of the RGB LED.
  • channel – channel to set the duty cycle of.
  • duty_cycle – desired duty cycle of the LED.
class j5.components.Servo(identifier: int, backend: j5.components.servo.ServoInterface)[source]

Bases: j5.components.component.Component

A standard servomotor.

identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.servo.ServoInterface][source]

Get the interface class that is required to use this component.

Returns:interface class.
position

Get the current position of the Servo.

Returns:current position of the Servo
class j5.components.ServoInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required to control a Servo.

get_servo_position(identifier: int) → Optional[float][source]

Get the position of a servo.

Parameters:identifier – Port of servo to check.
Returns:Position of servo.
set_servo_position(identifier: int, position: Optional[float]) → None[source]

Set the position of a servo.

Parameters:
  • identifier – Port of servo to set position.
  • position – Position to set the servo to.
class j5.components.StringCommandComponent(identifier: int, backend: j5.components.string_command.StringCommandComponentInterface)[source]

Bases: j5.components.component.Component

A string command component.

This component allows the sending and receiving of commands to a board, so that custom ASCII protocols can be implemented. This is primarily aimed at Boards which can have custom firmware installed by the students that are using them.

execute(command: str) → str[source]

Execute the string command and return the result.

This function can be synchronous and blocking.

Parameters:command – command to execute.
Returns:result of command.
Raises:ValueError – command is not valid.
identifier

An integer to identify the component on a board.

Returns:component identifier.
static interface_class() → Type[j5.components.component.Interface][source]

Get the interface class that is required to use this component.

Returns:interface class.
class j5.components.StringCommandComponentInterface[source]

Bases: j5.components.component.Interface

An interface containing the methods required for string commands.

execute_string_command(command: str) → str[source]

Execute the string command and return the result.

This function can be synchronous and blocking.

Parameters:command – command to execute.
Returns:result