roverprocess package

roverprocess.RoverProcess module

class roverprocess.RoverProcess.RoverMessage(key, data)

Bases: tuple

RoverMessage is a named tuple with key and data fields.

data

Alias for field number 1

key

Alias for field number 0

class roverprocess.RoverProcess.RoverProcess(**kwargs)

Bases: multiprocessing.context.Process

RoverProcesses are modules that handle functionality of one component of the rover. RoverProcesses somewhat emulate an Arduino, in that there is a setup and loop function. They also provide an interprocess communication mechanism based on the publisher/subscriber design pattern.

class ReceiverThread(downlink, parent)

Bases: threading.Thread

ReceiverThread listens for incoming messages.

__init__(downlink, parent)

Constructor.

Parameters:

• downlink (multiprocessing.Queue) – The incomming message (multiprocessing) queue of the parent rover process.
• parent (roverprocess.RoverProcess.RoverProcess) – instance of the RoverProcess

run()

Run in a new thread. Loops until system shutdown. Waits for a new message to come onto the downlink queue, and if the RoverProcess has a method called on_<key>(), where <key> is the key of the incomming RoverMessage, that method is called with the message’s data as a parameter. Otherwise, the RoverProcess’s messageTrigger method is called with the message as a parameter.

RoverProcess.__init__(**kwargs)

Constructor, called in main.py automatically, don’t override this through inheritance.

Parameters:

• uplink (multiprocessing.Queue) – queue for outgoing messages
• downlink (multiprocessing.Queue) – queue for incomming messages

RoverProcess.cleanup()

Acts like a deconstructor. Shuts down the receiver thread. If you override this method, be sure to call RoverProcess.cleanup() to ensure everything shuts down properly.

RoverProcess.log(message, level='INFO')

Logs a message. Messages are logged to the console and a file, depending how things are setup in main.py.

Parameters:

• message – A string to log, can also be an integer, float etc.
• level (str) – A string representing the log level as defined in the standard python logging module. Can be one of: “NOTSET”, “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”

RoverProcess.loop()

Runs continually during the lifetime of the system. Defaults to sleep for one second.

RoverProcess.messageTrigger(message)

Generic message handler. Typically, you want to use an if/else statement on the message key and do different things depending on the key.

Parameters:message (RoverMessage) – A single rovermessage that was received.

RoverProcess.on_quit(message)

Callback for the “quit” message. Calls cleanup() and exits the process.

RoverProcess.publish(key, value)

Publishes a new RoverMessage to the rover system.

Parameters:

• key (str) – An identifier for the message.
• value – The actual contents/data of the message.

RoverProcess.run()

This is method is what runs in a new process. First the setup method is called, then the receiver thread is started, and finally the loop method is run in an infinite while loop.

RoverProcess.setup(args)

Treated as a pseudo constructor, initialization of the process. Arguments from the real constructor are passed in as <args>

RoverProcess.subscribe(key)

Subscribe this RoverProcess to messages identified by <key>

Parameters:key (str) – An identifier for the key you want to subscribe to.

RoverProcess.unsubscribe(key)

Un-subscribe this RoverProcess to messages identified by <key>

Parameters:key (str) – An identifier for the key you want to un-subscribe from.

RoverProcess.watchdogExtend(timeout)

Request to extend the Watchdog timeout.

Parameters:timeout (int) – The requested timeout in seconds.

RoverProcess.watchdogPet()

Notify the Watchdog that the process is still alive. Should be called once per loop.

RoverProcess.watchdogReset()

Force the Watchdog to reset internal state of hanging or crashed processes; potentially used when a companion process is expected to temporarily hang.

roverprocess.RoverServer module

class roverprocess.RoverServer.RoverServer(**kwargs)

Bases: roverprocess.RoverProcess.RoverProcess

Just a RoverProcess that adds an easy way to run a method in a new thread.

This just prevents you from having to create a new class that inherits from Thread for every new thread you want to make.

class WorkerThread(function, **kwargs)

Bases: threading.Thread

New thread that runs a given method/funciton.

__init__(function, **kwargs)

Initialize a thread to run a function.

Parameters:

• function – The function to run.
• kwargs – arguments to the function.

run()

Run the thread, called by Thread.start()

RoverServer.cleanup()

RoverServer.getDevice(port)

Returns a device instance of a port name Override this method to handle the particular device communication standard you are using.

Parameters:port (str) – Path to a particular instance of a device

RoverServer.getSubscription(port)

Get the subscription(s) of a device. Override this method to handle the particular device communication standard you are using.

Parameters:port (str) – Path to a particular instance of a device

RoverServer.listenToDevice(**kwargs)

Continualy read from a device and publish any received messages.

Parameters:port (str) – Path to a particular instance of a device

RoverServer.messageTrigger(message)

RoverServer.read_cmd(port)

Function for reading messages from a device. Override this method to handle the particular device communication standard you are using.

Parameters:port (str) – Name of which device to read from.

RoverServer.reqSubscription(port)

Request susbscriptions from a device. Subscribe to the message if we’re not subscribed already. Also store the device for later. Finally, spin up a thread to listen for incomming messages from the device.

Parameters:port (str) – Path to a particular instance of a device

RoverServer.send_cmd(message, port)

Function for sending a message to a device. Override this method to handle the particular device communication standard you are using.

Parameters:

• message – The rover message to send
• port (str) – The port name device instance to send it to.

RoverServer.spawnThread(function, **kwargs)

Spawns a new thread with the given function.

Functions need the following prototype:

def func(**kwargs):
        ...

including self if necessary.

Parameters:

• function – The function/method to run in a new thread
• kwargs – The arguments to pass into the function. (This is a multi parameter call)

roverprocess.StateManager module

class roverprocess.StateManager.StateManager(**kwargs)

Bases: roverprocess.RoverProcess.RoverProcess

Handles the IPC mechanism for the rover software.

The StateManager is somewhat unique, in that it must allways be enabled. Whenever a RoverProcess publishes a message, the message goes to the StateManager, and the StateManager decides where to push the message to next.

addSubscriber(key, pname)

Register a process as a subscriber to a key.

Parameters:

• key (str) – The key to subscribe to.
• pname (str) – The name of the process.

cleanup()

From RoverProcess, shut down the StateManager.

dumpSubscribers()

Returns a string of the subscriptions in the system. Legacy

messageTrigger(message)

From RoverProcess, called when a message comes in.

If the mesage is “subscribe”, subscribe that process to the desired key. If the message is “unsubscribe”, remove that process from the key subscription. Otherwise, forward the incomming message to all processes that are subscribed to that key.

removeSubscriber(key, pname)

Remove a process from a subscription.

Parameters:

• key (str) – The key to unsubscribe from.
• pname (str) – The name of the process to unsubscribe.

setup(args)

terminateState()

Send the quit message to all processes handled by the StateManager.

class roverprocess.StateManager.Watchdog(log, hanging, timeout=5)

Bases: threading.Thread

Watchdog thread maintains a list of all running processes and indicates to the parent which RoverProcess instances are frozen or taking too long in their main loop. The default time is 5 seconds, but it can be extended, or notified mid loop. For advanced applications, the entire watchdog timer state can be reset Watchdog processes are logged in the format {ProcessName : IsRunnung}

extend(timeout, processName)

Change the Watchdog timeout period. This can be a permanent change or just set temporaily then reverted with the string “PREVIOUS” once a longer method is completed.

Parameters:

• timeout (int) or (str) – Timeout period in seconds as an integer; or str(“PREVIOUS”) to rever to the last set timeout
• processName (str) – Process’ own name (in StateManager); the name of the process to watch.

getHanging()

Gets any currently hanging or crashed process names.

Returns:A [list] of process names that are hanging or crashed. If the internal state is corrupted it returns the string “Unknown Process” NOTE: This should probably raise an exception instead.

pet(processName)

Pet the Watchdog; all processes being watched must call this before the timer expires A processe that does not pet the watchdog is considered dead or hung.

Parameters:processName (str) – Process’ own name (in StateManager); the key of Watchdog state to reset.

reset(processName)

Reset all timeouts in the Watchdog state.

Parameters:processName (str) – Process’ own name (in StateManager) to show in log file.

run()

watch(processName)

Add a process to watch to the Watchdog state.

Parameters:processName (str) – Process’ own name (in StateManager); the name of the process to watch.

roverprocess.DriveProcess module

class roverprocess.DriveProcess.DriveProcess(**kwargs)

Bases: roverprocess.RoverProcess.RoverProcess

Handles driving the rover.

Takes joystick input from the web ui and commands the wheels to move. Uses RPM and current control modes.

on_joystick1(data)

Handles the left wheels for manual control. A joystick1 message contains: [x axis (float -1:1), y axis (float -1:1)]

on_joystick2(data)

Handles the right wheels for manual control. A joystick1 message contains: [x axis (float -1:1), y axis (float -1:1)]

on_triggerL(trigger)

Handles left wheel braking (requires current mode) A triggerL message is a float from -1 to 1.

on_triggerR(trigger)

Handles right wheel braking (requires current mode) A triggerR message is a float from -1 to 1.

setup(args)

Initialize drive mode (default=rpm).

roverprocess.DriveProcess.current_curve(f)

scales a float to a suitable current value :param f: value between -1 and 1. :type f: float

Returns:Float between -max_current and max_current

roverprocess.DriveProcess.rpm_curve(f)

scales a float to a suitable rpm value :param f: value between -1 and 1. :type f: float

Returns:Float between -max_rpm and max_rpm

roverprocess.GPSProcess module

Will update docs once NavigationProcess branch is merged.

class roverprocess.GPSProcess.GPSProcess(**kwargs)

Bases: roverprocess.RoverProcess.RoverProcess

class PiksiThread(parent)

Bases: threading.Thread

run()

GPSProcess.setup(args)

roverprocess.USBServer module

roverprocess.USBServer.BAUDRATE = 115200

The baudrate to use for serial communication.

class roverprocess.USBServer.USBServer(**kwargs)

Bases: roverprocess.RoverServer.RoverServer

Forwards RoverMessages to devices connected to USB.

The USBServer first polls all connected devices to see what messages they are subscribed to. The server then subscribes to those messages. When those messages are published by other processes, the USBServer will forward it to the appropriate device.

The USBServer also listens for incomming messages from each device, and publishes them to the rest of the system for other processes.

getDevice(port)

getSubscription(device)

loop()

Just print out the subscriptions.

read_cmd(device)

send_cmd(message, device)

setup(args)

Initialize subscription maps and find what messages devices are susbribed to.

roverprocess.WebServer module

roverprocess.ExampleProcess module

class roverprocess.ExampleProcess.ExampleProcess(**kwargs)

Bases: roverprocess.RoverProcess.RoverProcess

cleanup()

loop()

messageTrigger(message)

on_heartbeat(data)

on_respondTrue(data)

setup(args)

roverprocess.ExampleServer module

class roverprocess.ExampleServer.ExampleServer(**kwargs)

Bases: roverprocess.RoverServer.RoverServer

getSubscribed()

setup(args)

workerFunction(**kwargs)