Commanduino Library

This is the documentation for the Commanduino controller modules. Here, you will find the methods associated with Command Handler Module, Command Manager Module, and Lock module. For the documentation associated with the Arduino devices, please see the Command Devices Package page for more details.

Module contents

Custom library designed to interface with Arduino hardware, allowing for control of the boards via Python.

Subpackages

• Command Devices Package
  • Module contents
  • Command Analog Read Module
  • Command Analog Write Module
  • Command Device Module
  • Command Digital Read Module
  • Command Digital Write Module
  • Command Linear Accelerator Stepper Module
  • Command Servo Module
  • Register Module
• Devices Package
  • Axis Module

Command Handler Module

class commanduino.commandhandler.CommandHandler(delim=', ', term=';', cmd_decimal=2)

Bases: object

Represents the Command Handler which will handle commands to/from the Arduino hardware.

Args:

delim (chr): Delimiter of the command, default set to DEFAULT_DELIM(‘,’)

term (chr): Terminal character of the command, set to DEFAULT_TERM(‘;’)

cmd_decimal (int): Decimal of the command, default set to DEFAULT_CMD_DECIMAL(2)

add_command(command_id, callback_function)

Adds an Arduino command to the Handler.

Args:

command_id (str): The ID of the command.

callback_function (str): A copy of the command to “callback”.

add_default_handler(callback_function)

Adds a default handler to the device.

Args:

callback_function (str): A copy of the command to “callback”.

add_relay(command_id, callback_function)

Adds a relay to the Handler.

Args:

command_id (str): The ID of the command.

callback_function (str): A copy of the command to “callback”.

build_remaining(cmd_list)

Builds an Arduino command from a list of partial commands.

Args:

cmd_list (List): The list of command constituents.

forge_command(command_id, *args)

Creates a full Arduino command.

Args:

command_id (str): The ID of the command.

*args: Variable length argument list.

handle(cmd)

Handles a full command to/from the Arduino hardware.

Args:

cmd (str): The command to be handled.

process_char(a_char)

Processes a single character of a command.

Args:

a_char (chr): The character to be processed

process_serial(a_serial)

Processes the serial communication to obtain data to be processed.

Args:

a_serial (int): The serial to read from.

process_string(a_string)

Processes a full string in the command.

Args:

a_string (str): The string to be processed.

remove_command(command_id, callback_function)

Removes an Arduino command from the Handler.

Args:

command_id (str): The ID of the command.

callback_function (str): A copy of the command to “callback”.

remove_default_handler(callback_function)

Removes a default handler from the device.

Args:

callback_function (str): A copy of the command to “callback”.

remove_relay(command_id, callback_function)

Removes a relay form the Handler.

Args:

command_id (str): The ID of the command.

callback_function (str): A copy of the command to “callback”.

set_command_decimal(cmd_decimal)

Sets the decimal of the Arduino command.

Args:

cmd_decimal (int): The decimal of the command.

set_command_header(cmd_header, addDelim=True)

Sets the header of the Arduino command.

Args:

cmd_header (chr): The header of the command.

addDelim (bool): Adds a delimiter to the command, default set to True.

class commanduino.commandhandler.SerialCommandHandler(port, baudrate=115200, timeout=0.01, delim=', ', term=';', cmd_decimal=2)

Bases: threading.Thread, commanduino.commandhandler.CommandHandler

Represents the Command Handler which will handle commands to/from the Arduino hardware via Serial Communication.

Args:

port (str): The port to communicate over.

baudrate (int): The baudrate of the serial communication, default set to DEFAULT_BAUDRATE (115200)

timeout (float): The time to wait for timeout, default set to DEFAULT_TIMEOUT (0.01)

delim (chr): The delimiting character of a command, default set to DEFAULT_DELIM (‘,’)

term (chr): The terminal character of a command, default set to DEFAULT_TERM (‘;’)

cmd_decimal (int): The decimal of the command, default set to DEFAULT_CMD_DECIMAL (2)

close()

Closes the serial communication between the PC and Arduino board.

classmethod from_config(serialcommand_config)

Obtains the details of the handler from a configuration.

Args:

cls (Class): THe instantiating class.

serialcommand_config (Dict): Dictionary containing the configuration details.

Returns:

SerialCommandHandler: New SerialCommandHandler object with details set from a configuration setup.

open(port, baudrate, timeout)

Opens the serial communication between the PC and Arduino board.

Args:

port (str): The port to communicate over.

baudrate (int): The baudrate of serial communication.

timeout (float): The time to wait for timeout.

run()

Starts the Handler processing commands.

send(command_id, *arg)

Sends a command over the serial communication.

Args:

command_id (str): The ID of the command.

*arg: Variable argument.

stop()

Releases the lock when signalled via an interrupt.

wait_until_running(sleep_time=0.01)

Waits until the current thread is running.

Args:

sleep_time (float): The time to wait for, default set to 0.01

write(msg)

Writes a message over the serial communication.

Args:

msg (str): The message to send.

Command Manager Module

exception commanduino.commandmanager.BonjourError(command_id)

Bases: exceptions.Exception

Exception for when Bonjour device is not available/not found.

class commanduino.commandmanager.CommandBonjour(serialcommandhandlers, timeout=0.1)

Bases: object

Represents a Command Manager for Bonjour devices.

Args:

serialcommandhandlers: Collection of SerialCommandHandler objects.

timeout (float): Time to wait before timeout, default set to DEFAULT_BONJOUR_TIMEOUT (0.1)

detect_device(command_id)

Attempts to detect the Bonjour device.

Args:

command_id (str): The ID of the command.

Returns:

cmdHdl (SerialCommandHandler): The Serial Command Handler.

bonjour_id (str): The Bonjour ID.

elapsed (float): Time elapsed since request.

get_bonjour_id(serialcommandhandler, command_id)

Obtains the device’s bonjour ID.

Args:

serialcommandhandler (SerialCommandHandler): The Serial Command Handler object.

command_id (str): The ID of the command.

Returns:

self.device_bonjour_id (str): The Bonjour ID.

is_valid (bool): Validity of the ID.

elapsed (float): Time elapsed since request.

handle_bonjour(*arg)

Handles the Bonjour initialisation.

Args:

*arg: Variable argument.

init_bonjour_info()

Initialises the Bonjour information.

send_bonjour(serialcommandhandler, command_id)

Sends a message to the device.

Todo

Fix this up

Args:

serialcommandhandler (SerialCommandHandler): The Serial Command Handler object.

command_id (str): The ID of the command.

class commanduino.commandmanager.CommandManager(serialcommand_configs, devices_dict, init_timeout=1, init_n_repeats=5)

Bases: object

Manages variying amounts of Command Handler objects.

Args:

serialcommand_configs (Tuple): Collection of serial command configurations.

devices_dict (Dict): Dictionary containing the list of devices.

init_timeout (int): Initialisation timeout, default se tto DEFAULT_INIT_TIMEOUT (1).

init_n_repeats (int): Number of times to attempt initialisation, default set to DEFAULT_INIT_N_REPEATS (5).

Raises:

OSError: Port was not found.

SerialException: Port was not found.

InitError: CommandManager on port was not initialised.

classmethod from_config(config)

Obtains the necessary information from a configuration setup.

Args:

cls (CommandManager): The instantiating class.

config (Dict): Dictionary contianing the configuration data.

classmethod from_configfile(configfile)

Obtains the configuration data from a configuration file.

Args:

cls (CommandManager): The instantiating class.

configfile (File): The configuration file.

handle_init(*arg)

Handles the initialisation of the Manager, ensuring that the threading locks are released.

Args:

*arg: Variable argument.

register_all_devices(devices_dict)

Registers all available Arduino devices.

Args:

devices_dict (Dict): Dictionary containing all devices.

register_device(device_name, device_info)

Registers an individual Arduino device.

Args:

device_name (str): Name of the device.

device_info (Dict): Dictionary containing the device information.

Raises:

DeviceRegisterError: Device is not in the device register.

BonjourError: Device has not been found.

request_and_wait_for_init(serialcommandhandler)

Requests initialisation and waits until it obtains a threading lock.

Args:

serialcommandhandler (SerialCommandHandler): Serial Command Handler object for communication.

request_init(serialcommandhandler)

Requests initialisation over serial communication.

Args:

serialcommandhandler (SerialCommandHandler): Serial Command Handler object for communication.

set_devices_as_attributes()

Sets the list of devices as attributes.

unrecognized(cmd)

Received command is unrecognised.

Args:

cmd (str): The received command.

wait_serial_device_for_init(cmdHdl)

Waits for initialisation using serial communication.

Args:

cmdHdl (CommandHandler): CommandHandler object to add/remove commands.

Returns:

elapsed (flaot): Time waited for initialisation.

Raises:

InitError: CommandManager on the port was not initialised.

exception commanduino.commandmanager.InitError(port)

Bases: exceptions.Exception

Exception for when the manager fails to initialise.

Lock module

class commanduino.lock.Lock(timeout=1, sleep_time=0.001)

Bases: object

Represents the Threading locks to be used throughout this library.

Args:

timeout (int): Time to wait until timeout, default set to 1.

sleep_time (float): Time to wait, default set to 0.001.

acquire()

Acquires a lock.

ensure_released()

Forces unlocking of a locked thread.

locked()

Checks if a thread is locked.

Returns:

self.lock.locked() (bool): Thread is locked/unlocked.

release()

Releases a lock.

wait_until_released()

Waits until the thread lock is released.

Returns:

False (bool): Elapsed time > the timeout.

True (bool): Elapsed time < timeout.

elapsed (float): Time taken to complete.