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,
undefon error
pin_mode ( pin, mode )
Set mode of Firmata device pin.
parm pin: Firmata device pin
param mode: use a member of constant $BASE from Device::Firmata::Constants
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 ( )"),
undefif 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
undefon error