tborg package

The TunderBorg API

by Carl J. Nobile

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

class tborg.tborg.ThunderBorg(bus_num=1, address=21, logger_name='', log_level=30, auto_set_addr=False, static_init=False)[source]

Bases: object

This module is designed to communicate with the ThunderBorg motor controller board.

COMMAND_ALL_OFF = 14

int: Switch everything off.

COMMAND_ANALOG_MAX = 1023

int: Maximum value for analog readings.

COMMAND_GET_A = 10

int: Get motor A direction and PWM rate.

COMMAND_GET_B = 13

int: Get motor B direction and PWM rate.

COMMAND_GET_BATT_LIMITS = 23

int: Get the battery monitoring limits.

COMMAND_GET_BATT_VOLT = 21

int: Get the battery voltage reading.

COMMAND_GET_DRIVE_A_FAULT = 15
int: Get the drive fault flag for motor A, indicates faults such as

short-circuits and under voltage.

COMMAND_GET_DRIVE_B_FAULT = 16
int: Get the drive fault flag for motor B, indicates faults such as

short-circuits and under voltage.

COMMAND_GET_FAILSAFE = 20

int: Get the failsafe flag.

COMMAND_GET_ID = 153

int: Get the board identifier.

COMMAND_GET_LED1 = 2

int: Get the color of the ThunderBorg LED.

COMMAND_GET_LED2 = 4

int: Get the color of the ThunderBorg Lid LED.

COMMAND_GET_LED_BATT_MON = 7

int: Get the state of showing the current battery level via the LEDs.

COMMAND_SET_ALL_FWD = 17

int: Set all motors PWM rate in a forwards direction.

COMMAND_SET_ALL_REV = 18

int: Set all motors PWM rate in a reverse direction.

COMMAND_SET_A_FWD = 8

int: Set motor A PWM rate in a forwards direction.

COMMAND_SET_A_REV = 9

int: Set motor A PWM rate in a reverse direction.

COMMAND_SET_BATT_LIMITS = 22

int: Set the battery monitoring limits.

COMMAND_SET_B_FWD = 11

int: Set motor B PWM rate in a forwards direction.

COMMAND_SET_B_REV = 12

int: Set motor B PWM rate in a reverse direction.

COMMAND_SET_FAILSAFE = 19
int: Set the failsafe flag, turns the motors off if communication is

interrupted.

COMMAND_SET_I2C_ADD = 170

int: Set a new I²C address.

COMMAND_SET_LED1 = 1

int: Set the color of the ThunderBorg LED.

COMMAND_SET_LED2 = 3

int: Set the color of the ThunderBorg Lid LED.

COMMAND_SET_LEDS = 5

int: Set the color of both the LEDs.

COMMAND_SET_LED_BATT_MON = 6

int: Set the color of both LEDs to show the current battery level.

COMMAND_VALUE_FWD = 1

int: I²C value representing forward.

COMMAND_VALUE_OFF = 0

int: I²C value representing off.

COMMAND_VALUE_ON = 1

int: I²C value representing on.

COMMAND_VALUE_REV = 2

int: I²C value representing reverse.

COMMAND_WRITE_EXTERNAL_LED = 24

int: Write a 32bit pattern out to SK9822 / APA102C.

DEFAULT_BUS_NUM = 1

int: Default I²C bus number.

DEFAULT_I2C_ADDRESS = 21

int: Default I²C address of the ThunderBorg board.

_BATTERY_MAX_DEFAULT = 35.0

float: Default maximum battery monitoring voltage

_BATTERY_MIN_DEFAULT = 7.0

float: Default minimum battery monitoring voltage.

_DEF_LOG_LEVEL = 30

int: The default logging level.

_DEVICE_PREFIX = '/dev/i2c-{}'

str: The I²C device prefix.

_I2C_ID_THUNDERBORG = 21

int: The Tunderborg I²C address.

_I2C_READ_LEN = 6

int: I²C read length.

_I2C_SLAVE = 1795

int: The I²C slave.

_MAX_VOLTAGE_MULT = 1.145

float: Maximum battery multiplier.

_POSSIBLE_BUSS = [0, 1]

list: Buss possibilities.

_PWM_MAX = 255

int: PWM maximum.

_VOLTAGE_PIN_CORRECTION = 0.0

float: Correction value for the analog voltage monitoring pin.

_VOLTAGE_PIN_MAX = 36.3

float: Maximum voltage from the analog voltage monitoring pin.

classmethod _auto_set_address(bus_num: int, tb: object) → bool[source]

Set the buss address.

Parameters:

  • bus_num (int) – I²C buss number.

  • tb (ThunderBorg) – The self object of the ThunderBorg class.

Returns:

If the address was set successfully.

Return type:

bool

classmethod _check_board_chip(recv: tuple, bus_num: int, address: int, tb: object) → bool[source]

Check if the board’s chip was found.

Parameters:

  • recv (tuple) – Data from COMMAND_GET_ID.

  • bus_num (int) – I²C bus number.

  • address (int) – I²C address of the ThunderBorg board.

  • tb (ThunderBorg) – The self object of the ThunderBorg class.

Returns:

If the board’s chip was found.

Return type:

bool

_get_drive_fault(command: int) → bool[source]

Get the drive fault.

Parameters:

command (int) – The command to run.

Returns:

The drive fault.

Return type:

bool

_get_led(command: int) → tuple[source]

Get the LED RGB values.

Parameters:

command (int) – The command to run.

Returns:

The LED RGB values.

Return type:

tuple

Raises:
_get_motor(command: int) → float[source]

Base motor speed retrieval method.

Parameters:

command (int) – Command to run.

Returns:

The level (speed) the motor is running at.

Return type:

float

classmethod _init_bus(bus_num: int, address: int, tb: object) → bool[source]

Check that the bus exists then initialize the board on the given address.

Parameters:

  • bus_num (int) – I²C bus number.

  • address (int) – I²C address of the ThunderBorg board.

  • tb (ThunderBorg) – The self object of the ThunderBorg class.

Returns:

If the device was found after initialization.

Return type:

bool

_initialize_board(bus_num: int, address: int, auto_set_addr: bool) → None[source]

Setup the I²C connections and file streams for read and write. If the default board cannot be found search for a board and if auto_set_addr is True configure the found board.

Parameters:

  • bus_num (int) – I²C bus number.

  • address (int) – I²C address of the ThunderBorg board.

  • auto_set_addr (bool) – If set to True will use the first board that is found. Default is False.

classmethod _is_thunder_borg_board(bus_num: int, address: int, tb: object) → bool[source]

Try to initialize a board on a given bus and address.

Parameters:

  • bus_num (int) – I²C bus number.

  • address (int) – I²C address of the ThunderBorg board.

  • tb (ThunderBorg) – The self object of the ThunderBorg class.

Returns:

If the thunder borg board was found.

Return type:

bool

_read(command: int, length: int, retry_count: int = 3) → list[source]

Reads data from the ThunderBorg.

Parameters:

  • command (int) – Command to send to the ThunderBorg.

  • length (int) – The number of bytes to read from the ThunderBorg.

  • retry_count (int) – Number of times to retry the read. Default is 3.

Returns:

A list of bytes returned from the ThunderBorg.

Return type:

list

Raises:

ThunderBorgException – If reading a command failed.

_set_led(command: int, r: float, g: float, b: float) → None[source]

Sets the LED color.

Parameters:

  • command (int) – The command to run.

  • r (float) – The LED red channel.

  • g (float) – The LED green channel.

  • b (float) – The LED blue channel.

_set_motor(level: int, fwd: int, rev: int) → None[source]

Sets the level and direction of a motor.

Parameters:

  • level (int) – Set motor level.

  • fwd (int) – The foward command.

  • rev (int) – The reverse command.

Raises:

ThunderBorgException – If there is an IOError or a ValueError.

_write(command: int, data: list) → None[source]

Write data to the ThunderBorg.

Parameters:

  • command (int) – Command to send to the ThunderBorg.

  • data (list) – The data to be sent to the I²C bus.

Raises:

ThunderBorgException – If the ‘data’ argument is the wrong type.

close_streams() → None[source]

Close both streams if the ThunderBorg was not found and when we are shutting down. We don’t want memory leaks.

classmethod find_board(bus_num: int = 1, tb: object = None, close: bool = True, logger_name: str = '') → list[source]

Scans the I²C bus for ThunderBorg boards and returns a list of all usable addresses.

Note

Rev 1 boards use bus number 0 and rev 2 boards use bus number 1.

Parameters:

  • bus_num (int) – The bus number where the address will be scanned. Default bus number is 1.

  • tb (ThunderBorg) – Use a pre-existing ThunderBorg instance. Default is None.

  • close (bool) – Default is True to close the stream before exiting.

Returns:

A list of all usable addresses.

Return type:

list

Raises:
get_battery_monitoring_limits() → float[source]

Read the current battery monitoring limits used for setting the LED color.

Note

The colors shown, range from full red at minimum or below, yellow half way, and full green at maximum or higher.

Returns:

Return a tuple of (minimum, maximum). The values are between 0.0 and 36.3 V.

Return type:

float

Raises:
get_battery_voltage() → int[source]

Read the current battery level from the main input.

Returns:

Return a voltage value based on the 3.3 V rail as a reference.

Return type:

int

Raises:
get_comms_failsafe() → bool[source]

Get the failsafe state.

Returns:

The failsafe state.

Return type:

bool

Raises:
get_drive_fault_one() → bool[source]

Read the motor drive fault state for motor one.

Note

  1. Faults may indicate power problems, such as under-voltage (not enough power), and may be cleared by setting a lower drive power.

  2. If a fault is persistent (repeatably occurs when trying to control the board) it may indicate a wiring issue such as indicated below.

  1. The supply is not powerful enough for the motors. The board has a bare minimum requirement of 6V to operate correctly. The recommended minimum supply of 7.2V should be sufficient for smaller motors.

  2. The + and - connections for the motor are connected to each other.

  3. Either + or - is connected to ground (GND, also known as 0V or earth).

  4. Either + or - is connected to the power supply (V+, directly to the battery or power pack).

  5. One of the motors may be damaged.

  1. Faults will self-clear, they do not need to be reset, however some faults require both motors to be moving at less than 100% to clear.

  2. The easiest way to run a check is to put both motors at a low power setting that is high enough for them to rotate easily. e.g. 30%

  3. Note that the fault state may be true at power up, this is normal and should clear when both motors have been driven.

Returns:

Return a False if there are no problems else a True if a fault has been detected.

Return type:

bool

Raises:
get_drive_fault_two() → bool[source]

Read the motor drive fault state for motor two.

Note

  1. Faults may indicate power problems, such as under-voltage (not enough power), and may be cleared by setting a lower drive power.

  2. If a fault is persistent (repeatably occurs when trying to control the board) it may indicate a wiring issue such as indicated below.

  1. The supply is not powerful enough for the motors. The board has a bare minimum requirement of 6V to operate correctly. The recommended minimum supply of 7.2V should be sufficient for smaller motors.

  2. The + and - connections for the motor are connected to each other.

  3. Either + or - is connected to ground (GND, also known as 0V or earth).

  4. Either + or - is connected to the power supply (V+, directly to the battery or power pack).

  5. One of the motors may be damaged.

  1. Faults will self-clear, they do not need to be reset, however some faults require both motors to be moving at less than 100% to clear.

  2. The easiest way to run a check is to put both motors at a low power setting that is high enough for them to rotate easily. e.g. 30%

  3. Note that the fault state may be true at power up, this is normal and should clear when both motors have been driven.

Returns:

Return a False if there are no problems else a True if a fault has been detected.

Return type:

bool

Raises:
get_led_battery_state() → bool[source]

Get the state of the LEDs between the default and the battery monitoring state.

Returns:

The True or False state of the LEDs between the default and the battery monitoring state.

Return type:

bool

Raises:
get_led_one() → tuple[source]

Get the current RGB color of the ThunderBorg LED number one.

Note

  1. (0, 0, 0) LED off

  2. (1, 1, 1) LED full white

  3. (1.0, 0.5, 0.0) LED bright orange

  4. (0.2, 0.0, 0.2) LED dull violet

Returns:

The current RGB color of the ThunderBorg LED number one.

Return type:

tuple

Raises:
get_led_two() → tuple[source]

Get the current RGB color of the ThunderBorg LED number two.

Note

  1. (0, 0, 0) LED off

  2. (1, 1, 1) LED full white

  3. (1.0, 0.5, 0.0) LED bright orange

  4. (0.2, 0.0, 0.2) LED dull violet

Returns:

The current RGB color of the ThunderBorg LED number two.

Return type:

tuple

Raises:
get_motor_one() → float[source]

Get the drive level of motor one.

Returns:

The drive level of motor one.

Return type:

float

Raises:
get_motor_two() → float[source]

Get the drive level of motor two.

Returns:

The drive level of motor two.

Return type:

float

Raises:
halt_motors() → None[source]

Halt both motors. Should be used when ending a program or when needing to come to an abrupt halt. Executing set_both_motors(0) essentially does the same thing.

Raises:
set_battery_limits(voltage_in: float) → None[source]

Guess the battery type NiMH or Li-ion then set the battery limits.

Parameters:

voltage_in (float) – The current voltage level.

set_battery_monitoring_limits(minimum: int, maximum: int) → None[source]

Set the battery monitoring limits used for setting the LED color.

Note

  1. The colors shown, range from full red at minimum or below, yellow half way, and full green at maximum or higher.

  2. These values are stored in EEPROM and reloaded when the board is powered.

Parameters:

  • minimum (float) – Value between 0.0 and 36.3 Volts.

  • maximum (float) – Value between 0.0 and 36.3 Volts.

Raises:
set_both_leds(r: float, g: float, b: float) → None[source]

Set the color of both of the ThunderBorg LEDs

Note

  1. (0, 0, 0) LED off

  2. (1, 1, 1) LED full white

  3. (1.0, 0.5, 0.0) LED bright orange

  4. (0.2, 0.0, 0.2) LED dull violet

Parameters:

  • r (float) – Range is between 0.0 and 1.0.

  • g (float) – Range is between 0.0 and 1.0.

  • b (float) – Range is between 0.0 and 1.0.

Raises:
set_both_motors(level: int) → None[source]

Set the drive level for motor two.

Parameters:

level (float) – Valid levels are from -1.0 to +1.0. A level of 0.0 is full stop. A level of 0.75 is 75% forward. A level of -0.25 is 25% reverse. A level of 1.0 is 100% forward.

Raises:
set_comms_failsafe(state: bool) → None[source]

Set the state of the motor failsafe. The default failsafe state of False will cause the motors to continuously run without a keepalive signal. If set to True the motors will shutdown after 1/4 of a second unless it is sent the speed command every 1/4 of a second.

Parameters:

state (bool) – If set to True failsafe is enabled, else if set to False failsafe is disabled. Default is disables when powered on.

Raises:
set_external_led_colors(colors: list) → None[source]

Takes a set of RGB values to set multiple LED devices like SK9822 and APA102C.

Note

  1. Each call will set all of the LEDs.

  2. Executing tb.set_external_led_colors([[1.0, 1.0, 0.0]]) will set a single LED to full yellow.

  3. Executing tb.set_external_led_colors([[1.0, 0.0, 0.0], [0.5, 0.0, 0.0], [0.0, 0.0, 0.0]]) will set LED 1 to full red, LED 2 to half red, and LED 3 to off.

Parameters:

colors (list) – The RGB colors for setting the LEDs.

Raises:
classmethod set_i2c_address(new_addr: int, cur_addr: int = -1, bus_num: int = 1, logger_name: str = '') → None[source]

Scans the I²C bus for the first ThunderBorg and sets it to a new I²C address. If cur_addr is supplied it will change the address of the board at that address rather than scanning the bus. The bus_num if supplied determines which I²C bus to scan using 0 for Rev 1 or 1 for Rev 2 boards. If bum_bus is not supplied it defaults to 1. Warning, this new I²C address will still be used after resetting the power on the device.

Parameters:

  • new_addr (int) – New address to set a ThunderBorg board to.

  • cur_addr (int) – The current address of a ThunderBorg board. The default of -1 will scan the entire range.

  • bun_num – The bus number where the address range will be found. Default is set to 1.

Raises:

  • KeyboardInterrupt – Keyboard interrupt.

  • ThunderBorgException – An error happened on a stream or failed to set the new address.

set_led_battery_state(state: bool) → None[source]

Change from the default LEDs state (set with set_led_one and/or set_led_two) to the battery monitoring state.

Note

If in the battery monitoring state the configured state is disabled. The battery monitoring state sweeps the full range between red (7V) and green (35V).

Parameters:

state (bool) – If True (enabled) LEDs will show the current battery level, else if False (disabled) the LEDs will be controlled with the set_led_* and the set_both_leds methods.

Raises:
set_led_one(r: float, g: float, b: float) → None[source]

Set the color of the ThunderBorg LED number one.

Note

  1. (0, 0, 0) LED off

  2. (1, 1, 1) LED full white

  3. (1.0, 0.5, 0.0) LED bright orange

  4. (0.2, 0.0, 0.2) LED dull violet

Parameters:

  • r (float) – Range is between 0.0 and 1.0.

  • g (float) – Range is between 0.0 and 1.0.

  • b (float) – Range is between 0.0 and 1.0.

Raises:
set_led_two(r: float, g: float, b: float) → None[source]

Set the color of the ThunderBorg LED number two.

Note

  1. (0, 0, 0) LED off

  2. (1, 1, 1) LED full white

  3. (1.0, 0.5, 0.0) LED bright orange

  4. (0.2, 0.0, 0.2) LED dull violet

Parameters:

  • r (float) – Range is between 0.0 and 1.0.

  • g (float) – Range is between 0.0 and 1.0.

  • b (float) – Range is between 0.0 and 1.0.

Raises:
set_motor_one(level: int) → None[source]

Set the drive level for motor one.

Parameters:

level (float) – Valid levels are from -1.0 to +1.0. A level of 0.0 is full stop. A level of 0.75 is 75% forward. A level of -0.25 is 25% reverse. A level of 1.0 is 100% forward.

Raises:
set_motor_two(level: int) → None[source]

Set the drive level for motor two.

Parameters:

level (float) – Valid levels are from -1.0 to +1.0. A level of 0.0 is full stop. A level of 0.75 is 75% forward. A level of -0.25 is 25% reverse. A level of 1.0 is 100% forward.

Raises:
write_external_led_word(b0: int, b1: int, b2: int, b3: int) → None[source]

Write low level serial LED 32 bit word to set multiple LED devices like SK9822 and APA102C.

Note

Bytes are written MSB (Most Significant Byte) first, starting at b0. e.g. Executing tb.write_external_led_word(255, 64, 1, 0) would send 11111111 01000000 00000001 00000000 to the LEDs.

Parameters:

  • b0 (int) – Byte zero

  • b1 (int) – Byte one

  • b2 (int) – Byte two

  • b3 (int) – Byte three

Raises:
exception tborg.tborg.ThunderBorgException[source]

Bases: Exception