mryslab / pymata_rh

Python API Library for RoboHat MM1

What is pymata_rh?

Pymata_rh is a Python 3 (Version 3.7 or above) Application Programming Interface (API). It is Windows, macOS and, Linux compatible, allowing you to easily create Python scripts to control and monitor the Robo HAT MM1.

Robot HAT MM1 Pin Names To Pin Number Map And Supported Pin Modes

MM1 Pin Name	Digital / Analog Pin #	Digital Input	Digital Output	PWM	Analog Input
Servo1	2	Yes	Yes	Yes	No
Servo2	3	Yes	Yes	Yes	No
Servo3	4	Yes	Yes	No	No
Servo4	5	Yes	Yes	No	No
Servo5	6	Yes	Yes	Yes	No
Servo6	7	Yes	Yes	Yes	No
Servo7	8	Yes	Yes	Yes	No
Servo8	9	Yes	Yes	Yes	No
NeoPixel	11	Yes	Yes	Yes	No
LED	13	No	Yes	No	No
RCC1	14 / A0	Yes	Yes	No	Yes
RCC2	15 / A1	Yes	Yes	No	Yes
RCC3	16 / A2	Yes	Yes	No	Yes
RCC4	17 / A3	Yes	Yes	No	Yes

NOTES:

• All digital pins support digital input pull-up mode.
• All analog input pins may be configured as digital inputs or outputs as well.
• Currently, there is no library support provided within pymata_rh to control NeoPixels. However, the pin may be used as a digital pin.

API Support

The API not only supports the pins and modes listed above, but the pymata_rh API also provides support for:

• Servo motors.
• The onboard INA219 current, shunt, and power monitor.
• The onboard MPU9250 nine-axis motion tracking device.
• External i2c devices.
• DHT 11 and 22 temperature sensors.
• HC-SR04 sonar distance sensors.

**NOTE: ** You may need to connect a power supply that provides adequate current capacity for your application.

A Demo GUI is included. After installing pymata-rh, open a terminal window and type: rhdemo

Use the GUI to control the RoboHAT without writing one line of code!

Implemented Using The Firmata Protocol

The API is implemented using the Firmata protocol in conjunction with FirmataExpress, custom firmware you install on the Robo HAT MM1. Communication between the Python script and the Robo HAT MM1 is accomplished over a serial link at 115200 baud.

A User's Guide is available, containing an annotated API as well as links to working examples.

Major features

• Fully documented intuitive API

• Python 3.7+ compatible.

• Set the pin mode and go!

• Data change events may be associated with a callback function, or each pin can be polled for its last event change.

  • Each data change event is time-stamped and logged.

Here is an example that demonstrates receiving asynchronous digital pin state data change notifications for pin 2 using callback notifications.

The API is quite simple to use. Here are the steps involved in creating a simple application.

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 pymata_rh executes the callback method you specified, the data parameter is populated with a list of items that describe the change event, including a time-stamp.

from pymata_rh import pymata_rh
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 pymata_rh API
        self.device = pymata_rh.PymataRh()

        # 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 2 For Digital Input changes
    DigitalInput(2)

Sample console output as input change events occur:

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

This project was developed with Pycharm

pymata_rh's Issues

Are pin modes limited for Arduino interface?

Looking at the Arduino API documentation
it appears that the supported pins and modes are limited as shown.
Those pins and modes work as shown.

Can the other pins and the supported pins support other modes? For example, RCC pins support digital input and output?
Also, are the pins not in the table available to the Arduino model?

Update docs to include the using the GUI demo.

Crowd Supply Update

Hi Alan,

I'm going to draft the latest CS update here.

Please feel free to provide examples, explanations, screenshots and outlines of what you have done with the Robo HAT MM1 (I know it is a lot 🥇 ).

High Level Summary so far:

• Firmata Express and Pymata
• Scratch
• OneGPIO Tkinter app

Please let me know if anything has been missed.

Backplane not autolaunched for rhgui

The rhgui program is not launching the backplane automatically.

pymata_rh and the Scratch extension have been released.

I have released pymata_rh to pypi. In addition, I have released the Scratch extension for th.e RoboHAT as well.

You can view the Scratch extension documentation here: https://mryslab.github.io/s3-extend/

If you wish to play with the extension, here is a summary of the steps to get things going:

1. Using pip install s3-extend.
2. Plug in a RoboHAT.
3. Open a terminal window and type:
   s3rh
   Hit return. It will take a few seconds for everything to come up.
4. Open Scratch using this link: https://mryslab.github.io/s3onegpio/
5. Load the RoboHAT extension into Scratch.

All of this assumes you will be running everything - s3-extend and browser, on the RPi. You can run Scratch remotely if you wish.
Instructions are here: https://mryslab.github.io/s3-extend/robohat_blocks/

Add OneGPIO Tkinter app to support RobotHAT

I am planning on creating a Tkinter application similar to the one shown below for the Arduino, but specifically for the RoboHAT.
Because this is going to use python-banyan, it means that the app can be run natively on the RPi or remotely on a different computer that is connected to the same network as the RPi. Also, since it is Python, it means that that computer can be Linux, macOS, or Windows without any changes.

This app will follow the python-banyan OneGPIO spec.

Missing Dependency - serial

The Pymata-RH installer does not install serial into the Python Environment.

should include pyserial as one of the pip install requirements