j5.components package¶

Subpackages¶

j5.components.derived package
- Submodules
  - j5.components.derived.ultrasound module
- Module contents

Submodules¶

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:	TypeError – duration must be a timedelta. ValueError – duration cannot be negative.

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:	TypeError – Pitch must be float or Note ValueError – Frequency must be greater than zero

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.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