/ 
Device-Firmata-0.69
River stage one • 1 direct dependent • 1 total dependent
/ Device::Firmata::Platform

NAME

Device::Firmata::Platform - Firmata API

DESCRIPTION

Provides the application programming interface for Device::Firmata implementing all major features of the Firmata 2.5 specification:

  • Analog Firmata

  • Digital Firmata

  • I2C Firmata

  • 1-Wire Firmata

  • Serial Firmata

  • Servo Firmata

  • Stepper Firmata

  • Firmata Scheduler

This API documentation is currently incomplete and only covers a small subset of the implementation. Anyone willing to help improve the documentation is welcome.

METHODS

attach ( ioPort )

Creates new Firmata Platform instance and attaches the provided I/O port.

  • param pkg: Perl package name or an instance of Device::Firmata::Platform

  • param ioPort: either an instance of Device::Firmata::IO::SerialIO or DDevice::Firmata::IO::NetIO or of any other class that provides compatible implementations for the methods data_read and data_write

  • return new Device::Firmata::Platform instance

After attaching the I/O port to the Firmata Platform the following sequence of operations is recommended:

  • 1. Call "probe ( )" to request the capabilities of the Firmata device.

  • 2. Call "pin_mode ( pin, mode )" to configure the pins of the Firmata device.

  • Periodically call "poll ( )" to processess messages from the Firmata device.

detach ( )

Detach IO port from Firmata Platform. Typically used only internally by "close ( )".

close ( )

Close IO port and detach from Firmata Platform.

system_reset ( )

Try to reset Firmata device. Will only work if Firmata device is connected.

messages_handle ( messages )

Receive identified message packets and convert them into their appropriate structures and parse them as required. Typically used only internally by "poll ( )".

sysex_handle ( sysexMessage)

Receive identified sysex packets and convert them into their appropriate structures and parse them as required. Typically used only internally by "messages_handle ( messages )".

probe ( )

On device boot time we wait 3 seconds for firmware name that the target device is using. If not received the starting message, then we wait for response another 2 seconds and fire requests for version. If the response received, then we store protocol version and analog mapping and capability.

  • return on success, undef on error

pin_mode ( pin, mode )

Set mode of Firmata device pin.

digital_write ( pin, state )

  • parm pin: Firmata device pin

  • param state: new state (0 or 1) for digial pin to set on Firmata device

Deprecation warning: Writing to pin with mode "PIN_INPUT" is only supported for backward compatibility to switch pullup on and off. Use sub "pin_mode ( pin, mode )" with $mode=PIN_PULLUP instead.

digital_read ( pin )

  • parm pin: Firmata device pin

  • return last state (0 or 1) of digital pin received from Firmata device

analog_read ( pin )

  • parm pin: Firmata device pin

  • return last value of analog pin received from Firmata device

analog_write ( pin, value )

  • parm pin: Firmata device pin

  • param state: new value for PWM pin to set on Firmata device

pwm_write ( pin, value )

pmw_write ( pin, value ) is an alias for "analog_write ( pin, value )"

poll ( )

Call this function every once in a while to check up on the status of the comm port, receive and process data from the Firmata device

observe_digital ( pin, observer, context )

Register callback sub that will be called by "messages_handle ( messages )" if a new value for a digital pin was received from the Firmata device.

  • parm pin: Firmata device pin

  • parm observer: callback sub reference with the parameters pin, oldState, newState, context

  • parm context: context value passed as last parameter to callback sub

observe_analog ( pin, observer, context )

Register callback sub that will be called by "messages_handle ( messages )" if the value of the analog pin received from the Firmata device has changed.

  • parm pin: Firmata device pin

  • parm observer: callback sub reference with the parameters pin, oldValue, newValue, context

  • parm context: context value passed as last parameter to callback sub

device_pin_to_analog_channel ( pin )

  • parm pin: Firmata device pin

  • return analog channel number if analog mapping is available (e.g. by calling "probe ( )"), undef if given pin is not mapped as an analog channel or given pin if analog mapping is not available

is_configured_mode ( pin, mode )

Verify if pin was configured with "pin_mode ( pin, mode )" for requested mode.

  • parm pin: Firmata device pin

  • param mode: use a member of constant $BASE from Device::Firmata::Constants

  • return 1 on success or undef on error

SEE ALSO

Device::Firmata::Constants