Skip to content
pymata4
A User's Guide


What is pymata4?

Pymata4 is a Python 3 compatible (Version 3.7 or above) Firmata Protocol client that, in conjunction with an Arduino Firmata sketch, permits you to control and monitor Arduino hardware remotely over a serial link.

Like its asyncio sibling pymata-express, pymata4 allows the user to take advantage of the advanced feature set of the FirmataExpress (recommended) or StandardFirmata Arduino server sketches.

A summary of pymata4's major features:

  • Applications are programmed using conventional Python 3.
  • Data change events may be associated with a callback function for asynchronous notification, or polling may be used when a synchronous approach is desired.
  • Each data change event is time-stamped and stored.
  • API Reference Documentation is available online.
  • A full set of working examples are available for download online.
  • Supports StandardFirmataWiFi.

Advantages of Using The FirmataExpress Sketch Over StandardFirmata:

  • The data link runs at 115200, twice the speed of StandardFirmata.
  • Advanced Arduino auto-discovery support is provided.
  • Additional hardware support is provided for:
    • HC-SR04 ultrasonic distance sensors.
    • DHT Humidity/Temperature sensors (in collaboration with Martyn Wheeler).
    • Stepper motors.
    • Tone generation for piezo devices.

An Intuitive And Easy To use API

For example, to receive asynchronous digital pin state data change notifications, you simply do the following:

  1. Set a pin mode for the pin and register a callback function.
  2. Have your application sit in a loop waiting for notifications.

When pymata4 executes your callback method, the data parameter will contain a list of items that describe the change event, including a time-stamp.

Here is an object-oriented example that monitors digital pin 12 for state changes:

from pymata4 import pymata4
import time

class DigitalInput:
    """
    Set a pin for digital input and received all data changes
    in the callback method
    """
    def __init__(self, pin):
        """
        Set a pin as a digital input
        :param pin: digital pin number
        """

        # Indices into the callback report data
        self.CB_PIN_MODE = 0
        self.CB_PIN = 1
        self.CB_VALUE = 2
        self.CB_TIME = 3

        # Instantiate this class with the pymata4 API
        self.device = pymata4.Pymata4()

        # Set the pin mode and specify the callback method.
        self.device.set_pin_mode_digital_input(pin, callback=self.the_callback)

        # Keep the program running and wait for callback events.
        while True:
            try:
                time.sleep(1)
            # If user hits Control-C, exit cleanly.
            except KeyboardInterrupt:
                self.device.shutdown()

    def the_callback(self, data):
        """
        A callback function to report data changes.
        This will print the pin number, its reported value
        the pin type (digital, analog, etc.) and
        the date and time when the change occurred

        :param data: [pin, current reported value, pin_mode, timestamp]
        """
        # Convert the date stamp to readable format
        date = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(data[self.CB_TIME]))

        # Print the pin, current value and time and date of the pin change event.
        print(f'Pin: {data[self.CB_PIN]} Value: {data[self.CB_VALUE]} Time Stamp: {date}')

if __name__ == '__main__':
    # Monitor Pin 12 For Digital Input changes
    DigitalInput(12)

Sample console output as input change events occur:

Pin: 12 Value: 0 Time Stamp: 2020-03-10 13:26:22
Pin: 12 Value: 1 Time Stamp: 2020-03-10 13:26:27

What You Will Find In This Document



Copyright (C) 2020 Alan Yorinks. All Rights Reserved.

Last updated 03 July 2020 For Release v1.10