Introduction

An Arduino pin can be configured to operate in one of several modes. The modes available to any given pin is dependent upon pin type.

For example, a digital pin may be configured for input, output, and for some digital pins, PWM output operation.

Analog input pins are even more flexible. They may be configured for analog input, digital input, or digital output operation.

Mapping Analog Pin Numbers To Digital Pin Numbers

When configuring an analog input pin as a digital input, you must use the pin's digital pin number equivalent. For example, on an Arduino Uno, if you wish to use pin A0 as a digital pin, the digital pin number equivalent is 14. In general, to find the digital equivalent of pin A0 for your specific Arduino board type, the algorithm is:

digital_pin_number = analog_pin_number + number of digital pins

Looking at the Uno: A0 = 14, A1 = 15, and so forth.

Looking at a Mega2560 which has 54 digital pins: A0 = 54, A1 = 55, etc.

Pymata4 requires that before using a pin, its mode must be explicitly set. This is accomplished using one of the pymata4 mode setting methods.

In this section, the methods to set pin modes are presented. For each API method, a link to an example is provided.

ANALOG PIN MODE

set_pin_mode_analog_input

 def set_pin_mode_analog_input(self, pin_number, callback=None, differential=1)

    Set a pin as an analog input.

    :param pin_number: arduino pin number

    :param callback: callback function

    :param differential: This value needs to be met for a callback to be invoked.

    callback returns a data list:

    [pin_type, pin_number, pin_value, raw_time_stamp]

    The pin_type for analog input pins = 2

Examples:

Notes:

When an analog input message is received from Firmata, the current reported data value is compared with that of the previously reported value. If the difference, either positive or negative, is greater than the differential parameter, then the callback is invoked. This is useful when you have a "noisy" input that may constantly fluctuate by a small value, and you wish to ignore the noise.
Pymata4 refers to analog pins using the numeric portion of the pin number only. For example, pin A3 is referred to as pin 3.
Data reporting via callbacks for this pin begins immediately after this method is called.

DIGITAL PIN MODES

set_pin_mode_digital_input

 def set_pin_mode_digital_input(self, pin_number, callback=None)

    Set a pin as a digital input.

    :param pin_number: arduino pin number

    :param callback: callback function

    callback returns a data list:

    [pin_type, pin_number, pin_value, raw_time_stamp]

    The pin_type for digital input pins = 0

Examples:

Notes:

Data reporting via callbacks for this pin begins immediately after this method is called.

set_pin_mode_digital_input_pullup

 def set_pin_mode_digital_input_pullup(self, pin_number, callback=None)

    Set a pin as a digital input with pullup enabled.

    :param pin_number: arduino pin number

    :param callback: callback function

    callback returns a data list:

    [pin_type, pin_number, pin_value, raw_time_stamp]

    The pin_type for digital input pins with pullups enabled = 11

Example:

digital_input_pullup.py

Notes:

Data reporting via callbacks for this pin begins immediately after this method is called.

set_pin_mode_digital_output

 def set_pin_mode_digital_output(self, pin_number)

    Set a pin as a digital output pin.

    :param pin_number: arduino pin number

Examples:

set_pin_mode_pwm_output

 def set_pin_mode_pwm_output(self, pin_number)

    Set a pin as a pwm (analog output) pin.

    :param pin_number:arduino pin number

Example: 1. pwm_analog_output.py

Notes:

Only specific digital pins support PWM mode. Check with the Arduino documentation to determine which pins support PWM for your board.

DEVICE TYPE PIN MODES

set_pin_mode_dht

def set_pin_mode_dht(self, pin_number, sensor_type=22, differential=.1, callback=None):
    """
    Configure a DHT sensor prior to operation.
    Up to 6 DHT sensors are supported

    :param pin_number: digital pin number on arduino.

    :param sensor_type: type of dht sensor
                        Valid values = DHT11, DHT12, DHT22, DHT21, AM2301

    :param differential: This value needs to be met for a callback
                         to be invoked.

    :param callback: callback function

    callback: returns a data list:

    [pin_type, pin_number, DHT type, humidity value, temperature raw_time_stamp]

    The pin_type for DHT input pins = 15

            ERROR CODES: If either humidity or temperature value:
                          == -1 Configuration Error
                          == -2 Checksum Error
                          == -3 Timeout Error
    """

Examples:

dht.py

Notes:

You may reset the differential value by calling this method again with new a differntial value.

set_pin_mode_i2c

def set_pin_mode_i2c(self, read_delay_time=0)

    Establish the standard Arduino i2c pins for i2c utilization.

    NOTE: THIS METHOD MUST BE CALLED BEFORE ANY I2C REQUEST IS MADE:
          This method initializes Firmata for I2c operations.

    :param read_delay_time (in microseconds): an optional parameter, default is 0

    NOTE: Callbacks are set within the individual i2c read methods of this API. 
          See i2c_read, i2c_read_continuous, or i2c_read_restart_transmission.

Example: 1. i2c_adxl345_accelerometer.py

set_pin_mode_servo

 def set_pin_mode_servo(self, pin, min_pulse=544, max_pulse=2400)

    Configure a pin as a servo pin. Set pulse min, max in ms.

    :param pin: Servo Pin.

    :param min_pulse: Min pulse width in ms.

    :param max_pulse: Max pulse width in ms.

Example: 1. servo.py

set_pin_mode_sonar

 def set_pin_mode_sonar(self, trigger_pin, echo_pin, callback=None, timeout=80000)

    This is a FirmataExpress feature.

    Configure the pins,ping interval and maximum distance for 
    an HC-SR04 type device.

    Up to a maximum of 6 SONAR devices is supported. 
    If the maximum is exceeded a message is sent to the console and 
    the request is ignored.

    NOTE: data is measured in centimeters. Callback is 
    called only when the the latest value received is different than the previous.

    :param trigger_pin: The pin number of for the trigger (transmitter).

    :param echo_pin: The pin number for the received echo.

    :param callback: optional callback function to report sonar data changes

    :param timeout: a tuning parameter. 80000UL equals 80ms.

    callback returns a data list:

    [pin_type, trigger_pin_number, distance_value (in cm), raw_time_stamp]

    The pin_type for sonar pins = 12

Example: 1. hc-sr04_distance_sensor.py

set_pin_mode_stepper

 def set_pin_mode_stepper(self, steps_per_revolution, stepper_pins)

    This is a FirmataExpress feature.

    Configure stepper motor prior to operation. 

    NOTE: Single stepper only. Multiple steppers not supported.

    :param steps_per_revolution: number of steps per motor revolution

    :param stepper_pins: a list of control pin numbers - either 4 or 2 pins

Example: 1. stepper.py

Notes: Only a single stepper motor is supported.

set_pin_mode_tone

 def set_pin_mode_tone(self, pin_number)

    This is a FirmataExpress feature.

    Set a PWM pin to tone mode.

    :param pin_number: arduino pin number

Example: 1. play_tone.py