Introduction: Going Beyond StandardFirmata - Adding New Device Support

INTRODUCTION

Have you ever thought of using Firmata for your Arduino project, only to find out that the device that you wish to use is not supported by Firmata? This article demonstrates the step by step approach I used to add stepper motor support to PyMata and to its associated Arduino Sketch, FirmataPlus. After reading this tutorial you should be ready to extend Firmata for your device.

Before We Begin - Some Background Information About Arduino/Firmata

So what is Firmata? Quoting from the Firmata web page, "Firmata is a generic protocol for communicating with microcontrollers from software on a host computer."

Arduino Firmata uses a serial interface to transport both command and report information between an Arduino microcontroller and a PC, typically using a serial/USB link set to a rate of 57600 bps. The data transferred across this link is binary in nature and the protocol is implemented in aclient/server model.

The server side is uploaded to an Arduino microcontroller in the form of an Arduino Sketch. The StandardFirmata Sketch, included with the Arduino IDE, controls the Arduino I/O pins, as commanded by the client, and it reports input pin changes, as well as other report information back to the client. FirmataPlus is an extended version of StandardFIrmata.

The Arduino client used for this article is PyMata. It is a Python application that is executed on a PC. It both sends commands to, and receives reports from, the Arduino server.

Why Use Firmata?

Arduino microcontrollers are wonderful little devices, but processor and memory resources are somewhat limited. For applications that are processor or memory intensive, there is often little choice but to offload the resource demand onto a PC in order for the application to be successful.

But that's not the only reason for using StandardFirmata. When developing lighter weight Arduino applications, a PC can provide tools and debugging capabilities not directly available on an Arduino microcontroller. Using a "fixed" client and server helps isolate variability to a PC application, where it is more easily managed. Once the application is perfected, it can be translated to a custom, standalone Arduino Sketch.

Why Use PyMata?

At the time of this writing, PyMata is the only Python client that implements the complete StandardFirmata protocol. It is a multi-platform library that supports Windows, MAC, and Linux operating systems right out of the box!

In addition, PyMata was designed so that users could easily extended it to support additional sensors and actuators, not currently supported by StandardFirmata.

Not long after PyMata was initially published, it was extended to support the Arduino Tone Library, and to support up to six simultaneous HC-SR04 type sonar distance sensors. The server side extensions for these features are provided in FirmataPlus.

Overview of the PyMata Client and FirmataPlus Server

PyMata is a high-performance multi-threaded Python application. Its "command thread" translates user API calls into Firmata protocol messages and forwards these messages to the Arduino microcontroller. The "reporter thread" receives, interprets and acts upon the Firmata messages received from the Arduino microcontroller.

A customized version of StandardFirmata, called FirmataPlus, is included with the PyMata distribution. It currently adds the following to StandardFirmata:

  • A Piezo device interface using the Arduino Tone Library
  • Support for multiple ultrasonic distance sensors using the NewPing library
  • Limited support (Arduino Uno only) for rotary encoders using the adafruit rotary encoder library
  • A debug print function to print internal Sketch values to the Python console.

Understanding Firmata Data Representation

Firmata uses a serial communications interface to transport data to and from the Arduino. The Firmata communications protocol is derived from the MIDI protocol which uses one or more 7 bit bytes to represent data. Because 7 bits can hold a maximum value of 128, a data item that has a value greater than 128, must be "disassembled" into multiple 7 bit byte chunks before being marshaled across the data link. By convention, the least significant byte (LSB) of a data item is sent first, followed by increasingly significant components of the data item. The the most significant byte (MSB) of the data item is the last data item sent.

So for example, if a parameter called max_distance with a decimal value of 525 needs to be sent across the serial link, it first needs to be "disassembled" into 7 bit chunks.

Here is a discussion of how this is accomplished:

The value 525 decimal is equivalent to the hexadecimal value of 0x20D, a 2 byte value. To get the LSB, we mask the value by AND'ing it with 0x7F. Both "C" and Python implementations are shown below:

// "C" implementation to isolate LSB
int max_distance_LSB = max_distance & 0x7f ; // mask the lower byte

# Python implementation to isolate LSB
max_distance_LSB = max_distance & 0x7F # mask the lower byte

After masking, max_distance_LSB will contain 0x0d. 0x20D & 0x7F = 0x0D


Next, we need to isolate the MSB for this 2 byte value. To do this, we will shift the value of 0x20D to the right, 7 places.

// "C" implementation to isolate MSB of 2 byte value
int max_distance_MSB = max_distance >> 7 ; // shift the high order byte 

# Python implementation to isoloate MSB of 2 byte value
max_distance_MSB = max_distance >> 7 # shift to get the upper byte

After shifting, max_distance_MSB will contain a value of 0x04.


When the "chunkified" marshaled data is received, it needs to be reassembled into a single value. Here is how the data is reassembled in both "C" and Python

// "C" implementation to reassemble the 2 byte, 
//     7 bit values into a single value
int max_distance = argv[0] + (argv[1] << 7) ; 

# Python implementation to reassemble the 2 byte, 
#    7 bit values into a single value
max_distance = data[0] + (data[1] << 7) 

After reassembly, the value once again equals 525 decimal or 0x20D hexadecimal.

This disassembly/reassembly processes may be performed by either the client or server.

Step 1: Before Writing Any Code, Analyze the Device Library Public Interface

Before creating or modifying any PyMata or FirmataPlus code to support a device, it is essential to understand how the device and its libraries function. For the stepper motor, the Simon Monk/adafruit tutorial provides excellent insight into using stepper motors and using the Arduino Stepper Library.

Let's look at how the Arduino Stepper library's public interface is defined in Stepper.h.

Stepper.h contains constructors to support both 2 conductor and 4 conductor motors. For each motor, the user specifies the number of steps per motor revolution, and the Arduino digital pin numbers that will control the motor.

class Stepper { 
  public:
    // constructors:
    Stepper(int number_of_steps, int motor_pin_1, 
                                 int motor_pin_2);


    Stepper(int number_of_steps, int motor_pin_1, 
                                 int motor_pin_2, 
                                 int motor_pin_3, 
                                 int motor_pin_4);

There is also a public method to set the speed of the motor:

    // speed setter method:
    void setSpeed(long whatSpeed);

A third public method specifies how to move the motor a given number of steps. Implied in this method is that a positive number moves the motor in one direction, and a negative number moves the motor in the opposite direction. This can be determined either by reading the implementation source code or by experimenting with the hardware.

    // mover method:
    void step(int number_of_steps);

The final public method retrieves the library's version number:

int version(void);

Step 2: Specifying and Designing the New PyMata API and Reporter Method Interfaces

Using the Stepper.h public interface as a guide, we can begin to design the PyMata stepper motor API and reporter method interfaces.

First, we need a method that will instruct the serial library to instantiate a motor object. Let's call this method, stepper_config, and similar to the stepper library's constructors, we will allow the caller to specify the number of steps per revolution, as well as to provide a list of motor control pins. This list, at the callers option, will contain 2 pin values for a 2 conductor motor or 4 values for a 4 conductor motor.

Here is the signature for the API method stepper_config.

def stepper_config(self, steps_per_revolution, stepper_pins):
    """
    Configure stepper motor prior to operation.
    @param steps_per_revolution: number of steps per motor revolution
    @param stepper_pins: a list of control pin numbers - either 4 or 2
    """

Referring to Stepper.h, the library provides separate methods to set the speed of the motor and to move the motor a given number of steps.

Our PyMata interface will need to do the same, but we are going to make a design decision and combine both operations into one method.

We will name this method stepper_step and its API signature is shown below.

def stepper_step(self, motor_speed, number_of_steps):
    """
    Move a stepper motor for the number of steps at the specified speed
    @param motor_speed: 21 bits of data to set motor speed
    @param number_of_steps: 14 bits for number of steps & direction
                            positive is forward, negative is reverse
    """

We also need to provide a method to allow the user to request the Stepper Motor Library version. Because of the asynchronous nature of Firmata reporting, we will need to provide separate methods to send the version request to the Arduino, and to retrieve the reply. Both of these methods are part of the public API.

The request method will have the following API signature:

def stepper_request_library_version(self):
    """
    Request the stepper library version from the Arduino.
    To retrieve the version after this command is called, call
    get_stepper_version().
    """

Before discussing the final API method, we need to specify the signature of the reporter method that processes the data sent from the Arduino to the client. This data is in the form of two 7 bit bytes that need to be reassembled to form the library version number that will be stored by the client.

def stepper_version_response(self, data):
    """
    This method handles a stepper library version message sent 
    from the Arduino and stores the value until the user requests 
    its value using get_stepper_version()
    @param: data -Two 7 bit bytes that contain the library version number
    """

The value returned by the Arduino in the stepper_version_response message will be stored internally by PyMata. To retrieve the value, the user calls the get_stepper_version API method. To allow for Arduino data transfer and processing times, a maximum wait time parameter is specified. The default value for this parameter is 20 seconds. If the Arduino replies before the maximum time expires, the value will be returned immediately and the timer is canceled. The signature for this method is:

def get_stepper_version(self, timeout=20):
    """
    @param timeout: specify a max time to allow arduino to process
                    and return the version
    @return: the stepper version number if it was set.
    """

An Important Note

All PyMata "command" methods are implemented in pymata.py. Therefore when we code stepper_config, stepper_step, stepper_request_library_version and get_stepper_version, they will all be added to pymata.py.

All "reporter messages" originating from the Arduino are handled by pymata_command_handler.py. Therefore the implementation of stepper_version_response will be added to that file.

Step 3: Selecting and Specifying the SysEx Command and Pin Mode

Firmata was designed to be user extensible. The mechanism that provides this extensibility is the System Exclusive (SysEx) messaging protocol.

The format of a SysEx message as defined by the Firmata Protocol, is shown in the illustration above. It begins with a START_SYSEX byte with a fixed value of hexadecimal 0xF0, and is followed by a unique SysEx command byte. The value of the command byte must be in the range of hexadecimal 0x00-0x7F. The command byte is then followed by an unspecified number of 7 bit data bytes and finally, the message is terminated with an END_SYSEX byte, that has a fixed value of hexadecimal 0xF7.

After receiving a complete SysEx command from a client, the server dispatches the command to the Sketch's sysexCallback() function, where it is processed.

// Excerpt From FirmataPlus.ino


/*=================================================================
 * SYSEX-BASED commands
 *================================================================*/
void sysexCallback(byte command, byte argc, byte *argv){
  byte mode;
  byte slaveAddress;
  byte slaveRegister;
  byte data;
  unsigned int delayTime;
  byte pin ;// used for tone
  int frequency ;
  int duration ;

  switch (command) {
      case STEPPER_DATA: // Process the command
          ....

To support a new device, we need to specify a new SysEx command, to be used by both the Firmata client and server. We also may need to specify a new pin mode.

Adding the New SysEx Command and Pin Mode to FirmataPlus.h

Using your favorite text editor, open FirmataPlus.h in the Arduino sketchbook. On my system this file is located at:

~/Arduino/libraries/FirmataPlus

Locate the User Defined Commands section of the file. Hexadecimal value 0x72 has not yet been assigned, so we will assign this value to our new command. To be consistent with Firmata naming conventions, the name of the new SysEx command will be STEPPER_DATA.

Enter the new command in the file as shown below:

/* user defined commands */

#define ENCODER_CONFIG		0x20 // create and enable encoder object
#define ENCODER_DATA            0x21 // current encoder data
#define TONE_DATA               0x5F // request a tone be played
#define SONAR_CONFIG            0x60 // configure a sonar distance
                                     // sensor for operation
#define SONAR_DATA              0x61 // Data returned from sonar 
                                     // distance sensor

/* New Command for stepper motor
#define STEPPER_DATA            0x72 // stepper motor command
*/

We also need to add a new pin mode for the stepper, and adjust the pin count in this file. There are 13 pin modes, including INPUT and OUTPUT.

// pin modes

//#define INPUT         0x00 // defined in wiring.h
//#define OUTPUT        0x01 // defined in wiring.h
#define ANALOG          0x02 // analog pin in analogInput mode
#define PWM             0x03 // digital pin in PWM output mode
#define SERVO           0x04 // digital pin in Servo output mode
#define SHIFT           0x05 // shiftIn/shiftOut mode
#define I2C             0x06 // pin included in I2C setup
#define ONEWIRE         0x07

// New Pin Mode
#define STEPPER          0x08 // Any pin in Stepper mode
//


#define TONE             0x09 // Any pin in TONE mode
#define ENCODER          0x0a
#define SONAR            0x0b // Any pin in Ping mode
#define IGNORE           0x7f

#define TOTAL_PIN_MODES         13

FirmataPlus.h editing is now complete. Save and close the file

Adding the SysEx command to pymata_command_handler.py

Now let's add the new SysEx command (0x72) to PyMata.

Using your favorite editor, open pymata_command_handler.py located in the PyMata-master/PyMata directory or in the directory where you unzipped the PyMata files.

Locate the Firmata sysex commands section and add the new command.

# Firmata sysex commands

SERVO_CONFIG = 0x70  # set servo pin and max and min angles
STRING_DATA = 0x71  # a string message with 14-bits per char

### New command
STEPPER_DATA = 0x72  # Stepper motor command
###


I2C_REQUEST = 0x76  # send an I2C read/write request
I2C_REPLY = 0x77    # a reply to an I2C read request
I2C_CONFIG = 0x78   # config I2C settings such as delay times
REPORT_FIRMWARE = 0x79  # report name and version of the firmware
SAMPLING_INTERVAL = 0x7A  # modify the sampling interval

Save and close this file.

Adding the Pin Mode to pymata.py

Finally, we need to add the pin mode to pymata.py.

Using your favorite editor, open pymata.py and add the new pin mode.

# pin modes

INPUT = 0x00  # pin set as input
OUTPUT = 0x01  # pin set as output
ANALOG = 0x02  # analog pin in analogInput mode
PWM = 0x03  # digital pin in PWM output mode
SERVO = 0x04  # digital pin in Servo output mode
I2C = 0x06  # pin included in I2C setup
ONEWIRE = 0x07  # possible future feature

### New Pin Mode
STEPPER = 0x08  # any pin in stepper mode
###


TONE = 0x09  # Any pin in TONE mode
ENCODER = 0x0a
SONAR = 0x0b  # Any pin in SONAR mode
IGNORE = 0x7f

PyMata does not use TOTAL_PIN_MODES, and there it is not added to this file. Save and close this file.

NOTE: Currently only input pin mode types are actually being used by the PyMata code, but we are adding both input and output pin mode pin types to be consistent with the FirmataPlus code.

Step 4: Defining the SysEx Protocol Messages

In the previous step, we could have assigned separate SysEx commands for each of the operations that need to be performed to configure and control the motor. However, we chose to assign only one value, STEPPER_DATA, to help conserve the limited number of available SysEx commands.

So, in order to have a STEPPER_DATA command perform one of the three operations specified by our previously defined PyMata API methods, a qualifier byte or subcommand, will be added to the STEPPER_DATA message. The diagram above shows the qualifier bytes that differentiate the STEPPER_DATA commands.

Below, we repeat the API method signatures as a reference, as well as show the protocol specification for each subcommand, byte by byte.

Note that the command protocol messages are originated from PyMata and are sent to FirmataPlus.

Also note that the API method stepper_request_library_version(), does not involve the Firmata protocol. It simply returns a previously stored value that is retained by PyMata.

STEPPER_CONFIGURE

API Method Definition:

def stepper_config(self, steps_per_revolution, stepper_pins)

// stepper motor configuration message definition for 2 conductor motor

0  START_SYSEX                     (0xF0)
1  STEPPER_DATA                    (0x72)
2  STEPPER_CONFIGURE               (0x00)
3  steps per revolution LSB        
4  steps per revolution MSB
5  motor control pin 1
6  motor control pin 2
7  END_SYSEX (0xF7)
// stepper motor configuration message definition for 4 conductor motor

0  START_SYSEX                     (0xF0)
1  STEPPER_DATA                    (0x72)
2  STEPPER_CONFIGURE               (0x00)
3  steps per revolution LSB        
4  steps per revolution MSB
5  motor control pin 1
6  motor control pin 2
7  motor control pin 3
8  motor control pin 4
9  END_SYSEX (0xF7)

STEPPER_STEP

API Method Definition:

def stepper_step(self, motor_speed, number_of_steps)

// stepper motor motion message

0  START_SYSEX                     (0xF0)
1  STEPPER_DATA                    (0x72)
2  STEPPER_STEP                    (0x01)
3  motor speed LSB                 motor speed has a maximum of 21 bits
4  motor speed bits 8-14
5  motor speed MSB
6  number of steps to move LSB
7  number of steps to move MSB
8  motor direction                 determined within stepper_step method
9  END_SYSEX (0xF7)

STEPPER_LIBRARY_VERSION

API Method Definition:

def stepper_request_library_version(self)

// stepper motor request library version

0  START_SYSEX                     (0xF0)
1  STEPPER_DATA                    (0x72)
2  STEPPER_LIBRARY_VERSION         (0x02)
3  END_SYSEX                       (0xF7)

The reply to the library version request is the only report message sent from the Arduino for the stepper motor. Therefore we can simply use the STEPPER_DATA message without any subcommand qualifier. If there were additional report types for the stepper motor, then we would need to add additional qualifiers for the reports.

Note that the report message is originated from FirmataPlus and sent to PyMata

// stepper motor version reply

0  START_SYSEX                     (0xF0)
1  STEPPER_DATA                    (0x72)
2  version LSB              
3  version MSB 
4  END_SYSEX                       (0xF7)

Step 5: Adding STEPPER_DATA Subcommands to Both the Client and Server Code

Using your favorite text editor, open pymata.py and add the stepper motor subcommands below the tone command section:

#  Tone commands
    TONE_TONE = 0  # play a tone
    TONE_NO_TONE = 1  # turn off tone 

# Stepper Motor Sub-commands
    STEPPER_CONFIGURE = 0  # configure a stepper motor for operation
    STEPPER_STEP = 1  # command a motor to move at the provided speed
    STEPPER_LIBRARY_VERSION = 2  # used to get stepper library version number

Save and close the file

Now using your text editor, open the FirmataPlus Sketch, FirmataPlus.ino and add the stepper motor subcommands below the Tone commands.

// SYSEX command sub specifiers

#define TONE_TONE 0
#define TONE_NO_TONE 1 

#define STEPPER_CONFIGURE 0
#define STEPPER_STEP 1
#define STEPPER_LIBRARY_VERSION 2

Save and close the file.

Notice that the same values are used by both the client and server.

Step 6: Implementing the PyMata API Command and Report Methods

COMMAND MESSAGES - pymata.py

Next we code the PyMata API methods for the three stepper motor sub-commands and an API method to retrieve the reported version number. All code changes for the API are made to pymata.py. The first three methods, stepper_config, stepper_step, and stepper_request_library_version translate the command into a properly formatted SysEx command that is then sent to the Arduino. The last method, get_stepper_version, does not result in any SysEx messaging, but simply returns the result for a previous version request.

  def stepper_config(self, steps_per_revolution, stepper_pins):
      """
      Configure stepper motor prior to operation.
      @param steps_per_revolution: number of steps per motor revolution
      @param stepper_pins: a list of control pin numbers - either 4 or 2
      """
      data = [self.STEPPER_CONFIGURE, steps_per_revolution & 0x7f, steps_per_revolution >> 7]
      for pin in range(len(stepper_pins)):
          data.append(stepper_pins[pin])
      self._command_handler.send_sysex(self._command_handler.STEPPER_DATA, data)
    def stepper_step(self, motor_speed, number_of_steps):
        """
        Move a stepper motor for the number of steps at the specified speed
        @param motor_speed: 21 bits of data to set motor speed
        @param number_of_steps: 14 bits for number of steps & direction
                                positive is forward, negative is reverse
        """
        if number_of_steps > 0:
            direction = 1
        else:
            direction = 0
        abs_number_of_steps = abs(number_of_steps)
        data = [self.STEPPER_STEP, motor_speed & 0x7f, (motor_speed >> 7) & 0x7f, motor_speed >> 14,
                abs_number_of_steps & 0x7f, abs_number_of_steps >> 7, direction]
        self._command_handler.send_sysex(self._command_handler.STEPPER_DATA, data)
    def stepper_request_library_version(self):
        """
        Request the stepper library version from the Arduino.
        To retrieve the version after this command is called, call
        get_stepper_version
        """
        data = [self.STEPPER_LIBRARY_VERSION]
        self._command_handler.send_sysex(self._command_handler.STEPPER_DATA, data)

Finally we implement get_stepper_library_version:

def get_stepper_version(self, timeout=20):
        """
        @param timeout: specify a time to allow arduino to process and return a version
        @return: the stepper version number if it was set.
        """
        # get current time
        start_time = time.time()
        # wait for version to come from the Arduino
        while self._command_handler.stepper_library_version <= 0:
            if time.time() - start_time > timeout:
                print "Stepper Library Version Request timed-out. Did you send a stepper_request_library_version command?"
                return
            else:
                pass
        return self._command_handler.stepper_library_version

This completes all the changes to pymata.py. Close and save pymata.py.


REPORT MESSAGES - pymata_command_handler.py

We will now add the report handler method to pymata_command_handler.py, so that it may receive and process stepper library version reports. Notice that this method reassembles the data from the the SysEx message and stores it in an internal variable called stepper_library_version.

    def stepper_version_response(self, data):
        """
        This method handles a stepper library version message sent from the Arduino
        @param: data - two 7 bit bytes that contain the library version number
        """
        self.stepper_library_version = (data[0] & 0x7f) + (data[1] << 7)

Finally, we need to update the command_dispatch table to process the receipt of the stepper version response. Add a new entry to the bottom of the existing table for STEPPER_DATA as shown below. Each entry in the command_dispatch table consists of the SysEx command, the name of the handling method, and the number of 7 bit values returned. The 7 bit values will be reassembled and interpreted as specified by the SysEx message formats we defined earlier.

    def run(self):
        """
        This method starts the thread that continuously runs to receive and interpret
        messages coming from Firmata. This must be the last method in this file
        It also checks the deque for messages to be sent to Firmata.
        """
        # To add a command to the command dispatch table, append here.
        self.command_dispatch.update({self.REPORT_VERSION: [self.report_version, 2]})
        self.command_dispatch.update({self.REPORT_FIRMWARE: [self.report_firmware, 1]})
        self.command_dispatch.update({self.ANALOG_MESSAGE: [self.analog_message, 2]})
        self.command_dispatch.update({self.DIGITAL_MESSAGE: [self.digital_message, 2]})
        self.command_dispatch.update({self.ENCODER_DATA: [self.encoder_data, 3]})
        self.command_dispatch.update({self.SONAR_DATA: [self.sonar_data, 3]})
        self.command_dispatch.update({self.STRING_DATA: [self._string_data, 2]})
        self.command_dispatch.update({self.I2C_REPLY: [self.i2c_reply, 2]})
        self.command_dispatch.update({self.CAPABILITY_RESPONSE: [self.capability_response, 2]})
        self.command_dispatch.update({self.PIN_STATE_RESPONSE: [self.pin_state_response, 2]})
        self.command_dispatch.update({self.ANALOG_MAPPING_RESPONSE: [self.analog_mapping_response, 2]})
        self.command_dispatch.update({self.STEPPER_DATA: [self.stepper_version_response, 2]})

The command dispatch table is defined as a map in pymata_command_handler.py. These code comments explain its use and how to append new commands to it.

# This is a map that allows the look up of command handler methods using a command as the key.

# This is populated in the run method after the python interpreter "sees" all of the 
  command handler method defines (python does not have forward referencing)
# The "key" is the command, and the value contains is a list containing the  method name 
  and the number of
# parameter bytes that the method will require to process the message (in some cases the 
  value is unused)


command_dispatch = {}

Save and close pymata_command_handler.py. The client changes are now complete.

Step 7: Implementing the FirmataPlus Sketch Code

Again, using your text editor, open FirmataPlus.ino and make the following changes:

1. Add stepper.h to the list of "header includes" near the top of the file:

 #include <Stepper.h>

2. Create a pointer to an instance of a stepper motor and set it to NULL. The stepper variable is global, so place it in the Global Variables section of the file.

/*==============================================================
        GLOBAL VARIABLES
  ==============================================================*/
// Stepper Motor 
Stepper *stepper = NULL; 

3. Add a case statement to switch(mode) in void setPinModeCallback(byte pin, int mode) for the stepper pin:

case STEPPER:
      pinConfig[pin] = STEPPER ;
      break ;
default:
      Firmata.sendString("Unknown pin mode");

4. Add a new case to void sysexCallback() to handle the STEPPER_DATA command and its subcommands.

case STEPPER_DATA:
      // determine if this a STEPPER_CONFIGURE command or STEPPER_OPERATE command
      if (argv[0] == STEPPER_CONFIGURE)
      {
        int numSteps = argv[1] + (argv[2] << 7);
        int pin1 = argv[3] ;
        int pin2 = argv[4] ;
        if ( argc == 5 )
        {
          // two pin motor
          stepper = new Stepper(numSteps, pin1, pin2) ;
        }
        else if (argc == 7 ) // 4 wire motor
        {
          int pin3 = argv[5] ;
          int pin4 = argv[6] ;
          stepper =  new Stepper(numSteps, pin1, pin2, pin3, pin4) ;
        }
        else
        {
          Firmata.sendString("STEPPER CONFIG Error: Wrong Number of arguments");
          printData("argc = ", argc) ;
        }
      }
      else if ( argv[0] == STEPPER_STEP )
      {
        long speed = (long)argv[1] | ((long)argv[2] << 7) | ((long)argv[3] << 14);
        int numSteps = argv[4] + (argv[5] << 7);
        int direction = argv[6] ;
        if (stepper != NULL )
        {
          stepper->setSpeed(speed) ;
          if (direction == 0 )
          {
            numSteps *= -1 ;
          }
          stepper->step(numSteps) ;
        }
        else
        {
          Firmata.sendString("STEPPER OPERATE Error: MOTOR NOT CONFIGURED");
        }
      }
      else if ( argv[0] == STEPPER_LIBRARY_VERSION )
      {
        if ( stepper != NULL )
        {
          int version = stepper->version() ;
          Firmata.write(START_SYSEX);
          Firmata.write(STEPPER_DATA);
          Firmata.write(version & 0x7F);
          Firmata.write(version >> 7);
          Firmata.write(END_SYSEX);
        }
        else
        {
          // did not find a configured stepper
          Firmata.sendString("STEPPER FIRMWARE VERSION Error: NO MOTORS CONFIGURED");
        }
        break ;
      }
      else
      {
        Firmata.sendString("STEPPER CONFIG Error: UNKNOWN STEPPER COMMAND");
      }
      break ;

5. In void SystemResetCallback() add the following code for stepper:

  // clear stepper pointer
  stepper = NULL ;

Close and save the file.

That concludes all of the code changes.

Step 8: Testing the New Functionality

First, using the Arduino IDE, compile and load the modified FirmataPlus.ino Sketch by selecting File/Examples/FirmataPlus that we just modified.

Next we need to install the new version of PyMata we created.

In an administrative Command Window, go to the directory where you extracted PyMata, and type :

python setup.py install 

or for Linux:

sudo python setup.py install

Next we want to run a test script Included with the PyMata distribution. In the PyMata examples directory, there is a python script called pymata_stepper_test.py (the code is shown below). To run this script, go to the examples directory and type:

python pymata_stepper_test.py

As shown in the YouTube video, you should see the motor spin one way and then the reverse.

SOURCE for pymata_stepper_test.py

from PyMata.pymata import PyMata import time
# Create an instance of PyMata.
firmata = PyMata("/dev/ttyACM0")
# send the arduino a firmata reset
firmata.reset()
# configure the stepper to use pins 9.10,11,12 and specify 512 steps per revolution
firmata.stepper_config( 512, [12, 11, 10, 9])
# allow time for config to complete
time.sleep(.5)
# ask Arduino to return the stepper library version number to PyMata
firmata.stepper_request_library_version()
# allow time for command and reply to go across the serial link
time.sleep(.5)
print "Stepper Library Version",
print firmata.get_stepper_version()
# move motor #0 500 steps forward at a speed of 20
firmata.stepper_step(20, 500)
# move motor #0 500 steps reverse at a speed of 20
firmata.stepper_step(20, -500)
# close firmata
firmata.close()

Step 9: Debugging the Arduino Firmata Sketch - Using SendString and PrintData

Because Firmata utilizes the Ardiuno serial interface, the Arduino IDE serial monitor cannot be used at the same time Firmata is running. This makes debugging a Firmata Sketch difficult to do.

Both StandrardFirmata and FirmataPlus implement the sendString method. This method packages string data and sends it to the client as part of STRING_DATA SysEx message . When PyMata receives a STRING_DATA SysEx message, it prints the message's contents to the Python console.

Sometimes though, we would like to print the current value of an internal Sketch variable accompanied by an identifier of some sort. FirmataPlus to the rescue! The printData function accepts an ID string and a data value as its input parameters, and sends each as STRING_DATA messages to the client. PyMata will print the debug information to the Python console making debugging a little easier.

Here is the FirmataPlus code for printData:

void printData(char * id,  long data)
{
  char myArray[64] ;

  String myString = String(data);
  myString.toCharArray(myArray, 64) ;
  Firmata.sendString(id) ;
  Firmata.sendString(myArray);
}

Step 10: Now It's Your Turn

We have come to the end of this tutorial, so let's summarize the steps needed to extend Firmata:

1. Spend the time to understand the operation of your selected device. Analyze any associated libraries for the device.

2. Using the knowledge gained in the previous step, craft the new PyMata API method interfaces,

3. Find an available Firmata SysEx command value as well as an available Firmata pin mode value within the Firmata server code. Add these values to both the client and server code.

4. Using step 2 above, identify the subcommands that will be needed to support the new API methods. Do this for both Command and Reporter messages. Add these values to both the client and sever code.

5. Define the new SysEx protocol messages in detail.

6. Implement both client and server code to support the new messages.

7. Test.

I hope you found this tutorial informative and that you will try extending Firmata on your own.

If you have any questions about this article, or PyMata/FirmataPlus, you may contact me at:

MisterYsLab@gmail.com

Thanks for reading!

Alan Yorinks