3.1. BB module

This module contains the main interface to interact with BlackBoard.

Author: Adrián Revuelta Cuauhtli <adrianrc.89@gmail.com>

Workplace: Bio-Robotics Lab., UNAM <http://bio-robotics.fi-p-unam.mx>

3.1.1. BB functions

pyrobotics.BB.Initialize(port, functionMap={}, asyncHandler=None)

Initializes BlackBoard with the corresponding parameters.

Parameters:

• port (int) – The port through which BlackBoard will communicate with this module.
• functionMap (dictionary) –

  A dictionary containing key:value pairs, where the key is the name of a command received (a string), and the value is either a tuple containing a function as a first element and a boolean as a second element, or a function. The function in both cases is the function that is going to execute the specified command and receives on object of type Command (See Creating a command handler). The boolean value indicates whether the execution of that command should be synchronous (on the same thread) or asynchronous, usually synchronous execution is preferred for fast commands that can answer almost immediately and asynchronous for commands that might take a little time. When the value is only a function, by default the execution is synchronous. functionMap can also contain an entry with a string containing only an asterisk, meaning that would be the handler in case no other handler is found for a specific command.

  Note

  Notice that although functionMap can include a wildcard handler and this might seem like the module could answer anything, BlackBoard will only send commands that are registered under this module’s configuration.

• asyncHandler (function) –

  A function that would handle the response of commands when sent with the method Send() instead of using SendAndWait(). This means the execution of a program that sends a command could continue and an asynchronous handler would handle the response when one is received.

  Note

  Notice that the asyncHandler functionality could also be achieved using a ParallelSender object, but it has other implications.

pyrobotics.BB.Start()

Once pyRobotics is initialized, you can start the communication with BlackBoard. This will start the threads of the internal ConnectionManager and CommandParser classes to start listening for a connection and start receiving and parsin messages.

If pyRobotics is not initialized it will only print a message saying “pyRobotics needs to be initialized before starting”. A similar message will show when trying to use some of this module’s functions before calling this function.

pyrobotics.BB.SetReady(val=True)

Once pyRobotics is initialized and started, this flag should be set to true to let BlackBoard know that the module is functioning correctly and ready to receive commands. Even if this module does not receive any commands, this should be set to true.

pyrobotics.BB.Wait()

In case this module is only used to receive and respond commands, but is doing nothing while no command is received, this will prevent the main thread (and therefore BlackBoard connection and commands execution) to terminate.

pyrobotics.BB.Send(message)

Sends a command WITHOUT waiting for an answer.

Parameters:message (Command) – Message to be sent, must be an instance of the Command class. Returns:True if the message was sent successfully, False otherwise.

pyrobotics.BB.SendAndWait(command, timeout=300000, attempts=1)

pyrobotics.BB.ReadSharedVar(name)

Reads the value of a Shared Variable from the BlackBoard.

Parameters:name (string) – The name of the Shared Variable. Returns:A SharedVar object if the request was successful, False if pyRobotics has not been started, None otherwise.

pyrobotics.BB.CreateSharedVar(sharedVarType, name)

Creates a Shared Variable in BlackBoard.

Parameters:

• sharedVarType (enum) – The type of the shared variable, it is one of the constants in SharedVarTypes pseudo-enum.
• name (string) – The name of the shared variable to be created.

Returns:

True if creation was successful, False otherwise.

pyrobotics.BB.WriteSharedVar(sharedVarType, name, data)

Writes content to a Shared Variable in BlackBoard.

Parameters:

• sharedVarType (enum) – The type of the shared variable, it is one of the constants in SharedVarTypes pseudo-enum.
• name (string) – The name of the shared variable to write to.
• data (var) – The data to be written, the type must match the shared variable’s type.

Returns:

True if shared variable was succesfully written to, False otherwise.

pyrobotics.BB.SubscribeToSharedVar(name, handler, subscriptionType='writeothers', reportType='content')

Subscribes to a Shared Variable in BlackBoard. When a module subscribes to a shared variable, it gets notifications when someone writes to it.

Parameters:

• name (string) – The name of the shared variable to subscribe to.
• handler (function) – A function that will be the handler for this shared variables notification. (See Creating a subscription handler)
• subscriptionType (enum) – The type of subscription, it is one of the constants in SubscriptionTypes pseudo-enum.
• reportType (enum) – The type of report to receive when someone writes to it, it is one of the constants in ReportTypes pseudo-enum.

Returns:

True if subscription was successful, False otherwise.