Processing Input Data

Before discussing the API, understanding how both Firmata generates input data notification messages, as well as how pymata-express processes these messages, may be beneficial in designing your application. Understanding the differences between using a callback versus polling is crucial when designing your application.

Firmata Data Collection

Both the FirmataExpress and StandardFirmata sketches poll all input pins within the loop method of the sketch.

Firmata builds notification messages containing the pin number, pin type, and data value, and transmits these messages to pymata-express over the serial link.

Firmata Data Polling

Digital Input

For digital input pins, all the pins are polled with each iteration of the sketch loop, with no delays. If the state of a pin has changed since the last loop iteration, Firmata creates a notification message and transmits the message over the serial link to pymata-express.

Analog Input

For analog input pins, each pin is polled, and its current value is reported, regardless of change. All analog input pins are nominally polled every 19 milliseconds.

I2C Input

Unlike digital and analog inputs, most I2C devices report values only when a read request is issued to the i2c device. For these i2c devices, a read request results in a single reply.

Some i2c devices may be placed in a continuous read mode. In this mode, the i2c device automatically sends update notifications, usually as quickly as possible. When in continuous i2c mode, the Firmata loop retrieves cached responses at a nominal polling rate of 19 milliseconds.

Sonar (HC-SR04) Input

FirmataExpress supports HC-SR04 type distance sensors. The Firmata loop polls each device and reports its current value regardless of change. The polling rate is nominally every 40 milliseconds for HC-SR04 type devices.

Using Pymata-Express To Access Input Data

Polling For Input Data Changes

As pymata-express receives input data notifications, it caches the data in internal data structures. These data structures retain the value reported as well as the time of occurrence. The application may query or poll these data structures to obtain the latest data updates for a given pin.

The pymata-express API methods that implement polling are:

analog_read
digital_read
i2c_read_saved_data
sonar_read

A more efficient and automatic way for your application to be notified of data updates is to use the pymata-express callback feature.

Using Callbacks Instead Of Polling

Callback notification is much more efficient than using polling.

A callback is simply a function or method written by you, that is called automatically by pymata-express when it receives an input data notification message from Firmata.

You may optionally register callback functions when using any of the following pymata-express API methods:

set_pin_mode_analog_input
set_pin_mode_digital_input
set_pin_mode_digital_input_pullup
set_pin_mode_sonar
enable_analog_reporting (an alias for set_pin_mode_analog_input)
i2c_read
i2c_read_continuous
i2c_read_restart_transmission

You may write a callback function for each input pin, write a callback function to handle any pin of single type, such as analog input or digital input, or even have a single callback function handle all input data notifications.

You may use callbacks with some pins while using polling for others. Polling is available for all input pins whether callbacks are in use or not.

A callback function is specified to accept a single input parameter, typically named data. The input parameter will be filled with a list when pymata-express invokes the callback. A description of what is contained in the list is provided in the reference API.

def my_callback(data):
    """
    :param data: a list containing pin type, pin number, 
                 data value and time-stamp
    """
# Your code goes here to process the data

TIP: You should keep callback functions as short as possible. If processing callback data within the callback function results in blocking your application, you may wish to consider spawning a separate processing thread.