BO.IOBoard Class
Creates an interface to the I/O board. The IOBoard object brokers the communication between your application and the physical I/O board. Currently you can only connect to a single I/O board per computer. However you could connect to multiple I/O boards if they are attached to multiple computers on your network. In that case you would create a separate IOBoard instance for each board you are connecting to in your network.
Constructor
BO.IOBoard
-
host
-
port
-
protocol
Parameters:
-
host
StringThe host address of the web server.
-
port
NumberThe port to connect to on the web server. Default = false.
-
protocol
String[optional] The websockt protocol definition (if necessary).
Item Index
Methods
- addEventListener
- analogToDigital
- begin
- checkForQueryResponse
- close
- disableAnalogPin
- disableDigitalPins
- dispatchEvent
- enableAnalogPin
- enableDigitalPins
- enablePullUp
- getAnalogPin
- getAnalogPinCount
- getDigitalPin
- getFirmwareName deprecated
- getFirmwareVersion
- getI2cPins
- getPin
- getPinCapabilities
- getPinCount
- getPins
- getProtocolVersion
- getSocket
- getValueFromTwo7bitBytes
- hasEventListener
- managePinListener
- onInitialVersionResult
- onSocketClosed
- onSocketConnection
- onSocketMessage
- parseInputMessage
- processAnalogMappingResponse
- processAnalogMessage
- processCapabilitiesResponse
- processDigitalMessage
- processInput
- processMultiByteCommand
- processPinStateResponse
- processQueryFirmwareResult
- processStatusMessage
- processSysexCommand
- processSysExString
- queryAnalogMapping
- queryCapabilities
- queryPinState
- removeEventListener
- reportCapabilities deprecated
- reportFirmware
- reportPinCapabilities
- reportVersion
- send
- sendAnalogData
- sendDigitalData
- sendDigitalPort
- sendDigitalPortReporting
- sendExtendedAnalogData
- sendOut
- sendServoAttach
- sendServoData
- sendString
- sendSysex
- setAnalogPinReporting
- setDigitalPinMode
- setDigitalPinValue
- startup
- startupInMultiClientMode
- systemReset
- toDec
Properties
Methods
addEventListener
-
type
-
listener
Parameters:
-
type
StringThe event type
-
listener
FunctionThe function to be called when the event is fired
analogToDigital
()
Number
Use this method to obtain the digital pin number equivalent for an analog pin.
Returns:
The digital pin number equivalent for the specified analog pin number.
Example:
// set analog pin A3 on an Arduino Uno to digital input
board.setDigitalPinMode(board.analogToDigital(3), Pin.DIN);
board.analogToDigital(3) returns 17 which is the digital equivalent of the analog pin
begin
()
private
Request the firmware version from the IOBoard.
checkForQueryResponse
()
private
Check if a capability response was received. If not, assume that a custom sketch was loaded to the IOBoard and fire a READY event.
close
()
private
A wrapper for the close method of the WebSocket. Making this private until a use case arises.
disableAnalogPin
-
pin
Call this method to disable analog input for the specified pin.
Parameters:
-
pin
NumberThe pin connected to the analog input
disableDigitalPins
()
Disables digital pin reporting for all digital pins.
dispatchEvent
-
type
-
optionalParams
Parameters:
-
type
EventThe Event object.
-
optionalParams
ObjectOptional parameters passed as an object. return {boolean} True if dispatch is successful, false if not.
enableAnalogPin
-
pin
Call this method to enable analog input for the specified pin.
Parameters:
-
pin
NumberThe pin connected to the analog input
enableDigitalPins
()
Enables digital pin reporting for all digital pins. You must call this before you can receive digital pin data from the IOBoard.
enablePullUp
-
pinNum
Enable the internal pull-up resistor for the specified pin number.
Parameters:
-
pinNum
NumberThe number of the input pin to enable the pull-up resistor.
getAnalogPin
()
Pin
Returns:
A reference to the Pin object (mapped to the IOBoard board analog pin).
getAnalogPinCount
()
Number
Returns:
The total number of analog pins supported by this IOBoard
getDigitalPin
()
Pin
Returns:
A reference to the Pin object (mapped to the IOBoard board digital pin).
getFirmwareName
()
String
deprecated
Returns:
The name of the firmware running on the IOBoard.
getFirmwareVersion
()
String
Returns:
The version of the firmware running on the IOBoard.
getI2cPins
()
Number
private
Returns undefined if the board does not have i2c pins.
Returns:
The pin numbers of the i2c pins if the board has i2c.
getPin
()
Pin
private
Returns:
An unmapped reference to the Pin object.
getPinCapabilities
()
Array
Returns the capabilities for each pin on the IOBoard. The array is indexed by pin number (beginning at pin 0). Each array element contains an object with a property for each modes (input, output, pwm, servo, i2c, etc) supported by the pin. The mode value is the resolution in bits.
Returns:
The capabilities of the Pins on the IOBoard.
getPinCount
()
Number
Returns:
Total number of pins
getPins
()
Pin
Returns:
An array containing all pins on the IOBoard
getProtocolVersion
()
String
Returns:
The version of Firmata protocol implemented by the firmware running on the IOBoard.
getSocket
()
WSocketWrapper
Returns:
A reference to the WebSocket
getValueFromTwo7bitBytes
-
lsb
-
msb
A utility method to assemble a single value from the 2 bytes returned from the IOBoard (since data is passed in 7 bit Bytes rather than 8 bit it must be reassembled. This is to be used as a protected method and should not be needed in any application level code.
Parameters:
-
lsb
NumberThe least-significant byte of the 2 values to be concatentated
-
msb
NumberThe most-significant byte of the 2 values to be concatenated
Returns:
The result of merging the 2 bytes
hasEventListener
-
type
Parameters:
-
type
StringThe event type return {boolean} True is listener exists for this type, false if not.
managePinListener
()
private
Ensure that event listeners are properly managed for pin objects as the pin type is changed during the execution of the program.
onInitialVersionResult
()
private
On startup, Firmata reports its version. Make sure the version is 2.3 or greater before proceeding. If the Firmata version is < 2.3 report this to the user (to do: throw appropriate error?).
onSocketClosed
()
private
Report that the websocket connection has been closed.
onSocketConnection
()
private
A websocket connection has been established.
onSocketMessage
-
event
A websocket message has been received.
Parameters:
-
event
ObjectThe message property is an array of one or more stringified bytes from the board or a config string from the server.
parseInputMessage
-
data
Determine if the incoming data is a config message or a byte.
Parameters:
-
data
StringA string representing a config message or an 8-bit unsigned integer.
processAnalogMappingResponse
()
private
Map map analog pins to board pin numbers. Need to do this because the capability query does not provide the correct order of analog pins.
processAnalogMessage
()
private
Process incoming analog data. The value is mapped from 0 - pin.analogReadResolution to a floating point value between 0.0 - 1.0.
processCapabilitiesResponse
()
private
Auto configure using capabilities response. This creates a configuration for any board in the Firmata boards.h file.
processDigitalMessage
-
port
-
bits0_6
-
bits7_13
Processing incoming digital data. Parse the port number and value to determine if any digital input data has changed. Dispatch an event if the value has changed.
Parameters:
-
port
NumberDigital data is sent per port. This does not align with the concept of a microcontroller port, but is a collection of 8 pins on the microcontroller.
-
bits0_6
NumberBits 0 - 6 of the port value.
-
bits7_13
NumberBits 7 - 13 of the port value.
processInput
-
inputData
Process input data from the IOBoard.
Parameters:
-
inputData
NumberNumber as an 8-bit unsigned integer
processMultiByteCommand
()
private
Incoming data is either multibyte or sysex. Route multibyte data to the appropriate method.
processPinStateResponse
()
private
Reads the current configuration of the requested pin. The following values are returned: 1: pin number, 2: pin type (0: DIN, 1: DOUT, 2: AIN, 3: AOUT / PWM, 4: SERVO, 5: SHIFT, 6: I2C), 3: pin state. The pin state for output modes is the value previously written to the pin. For input modes (AIN, DIN, etc) the state is typically zero (it is not the value that was written to the pin). For digital inputs the state is the status of the pullup resistor.
processQueryFirmwareResult
()
private
Construct the firmware name and version from incoming ascii data.
processStatusMessage
()
private
Process a status message from the websocket server
processSysexCommand
()
private
Route the incoming sysex data to the appropriate method.
processSysExString
()
private
Construct a String from an incoming ascii data.
queryAnalogMapping
()
private
Query which pins correspond to the analog channels
queryCapabilities
()
private
Query the cababilities and current state any board running Firmata.
queryPinState
-
pin
Reads the current state of the requested pin. Listen for the IOBoardEvent.PIN_STATE_RESPONSE event to get the response. The response contains a reference to the pin object with its state updated to match the current state of the pin on the IOBoard.
You should not typically need to call this method since the pin states are maintained client-side. Use the getAnalogPin or getDigitalPin to get the current state of a pin or getPins to get an array of all Pin objects for the IOBoard.
Cases for queryPinState are to update the pin state after a period of inactivity. For example if multiple client applications are using the same IOBoard (so multiple JavaScript apps connected to the same Arduino). When a new client connection is made, queryPinState is called automatically to copy the IOBoard pin state to the client. If for some reason you needed to copy the state of a single or multiple Pins again, you could call queryPinState in your application. In most cases however you should never need to call this method.
Parameters:
-
pin
PinThe pin object to query the pin state for.
removeEventListener
-
type
-
listener
Parameters:
-
type
StringThe event type
-
listener
FunctionThe function to be called when the event is fired
reportCapabilities
()
deprecated
reportFirmware
()
Request the name and version of the firmware (the sketch) running on the IOBoard. Listen for the IOBoard.FIRMWARE_VERSION event to be notified of when the name is returned from the IOBoard. The version number is also returned.
reportPinCapabilities
()
Call this method to print the capabilities for all pins to the console.
reportVersion
()
Request the Firmata protocol version implemented in the firmware (sketch) running on the IOBoard. Listen for the IOBoard.PROTOCOL_VERSION event to be notified of when the Firmata version is returned from the IOBoard.
send
-
message
A wrapper for the send method of the WebSocket I'm not sure there is a case for the user to call this method So I'm making this private for now.
Parameters:
-
message
NumberMessage data to be sent to the IOBoard
sendAnalogData
-
pin
Sends an analog value up to 14 bits on an analog pin number between 0 and 15. The value passed to this method should be in the range of 0.0 to 1.0. It is multiplied by the analog write (PWM) resolution set for the pin.
Parameters:
-
pin
NumberThe analog pin number. param {Number} value The value to send (0.0 to 1.0).
sendDigitalData
-
pin
-
value
Add the pin value to the appropriate digital port and send the updated digital port value.
Parameters:
-
pin
NumberThe digital pin number.
-
value
NumberThe value of the digital pin (0 or 1).
sendDigitalPort
-
portNumber
-
portData
Send the digital values for a port. Making this private for now.
Parameters:
-
portNumber
NumberThe number of the port
-
portData
NumberA byte representing the state of the 8 pins for the specified port
sendDigitalPortReporting
-
mode
Enable or disable reporting of all digital pins for the specified port.
Parameters:
-
mode
NumberEither Pin.On or Pin.OFF
sendExtendedAnalogData
-
pin
-
value
Sends an analog value > 14 bits and/or send a value for a pin number greater than 15.
Parameters:
-
pin
NumberThe analog pin number (up to 128).
-
value
NumberThe value to send (up to 16 bits).
sendOut
-
event
Called when ever a pin value is set via pin.value = someValue. Sends digital or analog output pin and output values to the IOBoard.
Parameters:
-
event
EventA reference to the event object (Pin in this case).
sendServoAttach
-
pin
-
minPulse
-
maxPulse
Call to associate a pin with a connected servo motor. See the documentation for your servo motor for the minimum and maximum pulse width. If you can't find it, then the default values should be close enough so call sendServoAttach(pin) omitting the min and max values.
Parameters:
-
pin
NumberThe pin the server is connected to.
-
minPulse
Number[optional] The minimum pulse width for the servo. Default = 544.
-
maxPulse
Number[optional] The maximum pulse width for the servo. Default = 2400.
sendServoData
-
pin
-
value
Send the servo angle.
Parameters:
-
pin
NumberThe digital pin number the servo is attached to.
-
value
NumberThe angle to rotate to (0.0 to 1.0 mapped to 0 - 180).
sendString
-
str
Send a string message to the IOBoard. This is useful if you have a custom sketch running on the IOBoard rather than StandardFirmata and want to communicate with your javascript message via string messages that you then parse in javascript. You can receive string messages as well.
To test, load the EchoString.pde example from Firmata->Examples menu in the IOBoard Application, then use sendString("your string message") to have it echoed back to your javascript application.
Parameters:
-
str
StringThe string message to send to the IOBoard
sendSysex
-
command
-
data
Send a sysEx message to the IOBoard. This is useful for sending custom sysEx data to the IOBoard, for example if you are not using StandardFirmata. You would likely use it in a class rather than calling it from your main application.
Parameters:
-
command
NumberThe sysEx command value (see firmata.org)
-
data
NumberA packet of data representing the sysEx message to be sent
setAnalogPinReporting
-
pin
-
mode
Call this method to enable or disable analog input for the specified pin.
Parameters:
-
pin
NumberThe pin connected to the analog input
-
mode
NumberPin.ON to enable input or Pin.OFF to disable input for the specified pin.
setDigitalPinMode
-
pin
-
mode
-
silent
Set the specified digital pin mode.
Parameters:
-
pin
NumberThe number of the pin. When using and analog pin as a digital pin, refer the datasheet for your board to obtain the digital pin equivalent of the analog pin number. For example on an Arduino UNO, analog pin 0 = digital pin 14.
-
mode
NumberPin.DIN, Pin.INPUT_PULLUP, Pin.DOUT, Pin.PWM, Pin.SERVO, Pin.SHIFT, or Pin.I2c
-
silent
Boolean[optional] Set to true to not send SET_PIN_MODE command. Default = false.
setDigitalPinValue
-
pin
-
value
Set the value of the specified pin
Parameters:
-
pin
NumberThe number of the digital pin.
-
value
NumberPin.HIGH or Pin.LOW
startup
()
private
The IOBoard is configured and ready to send and accept commands.
startupInMultiClientMode
()
private
Single client mode is the default mode. Checking the "Enable multi-client" box in the Breakout Server UI to enable multi-client mode.
systemReset
()
private
Resets the board to its default state without physically resetting the board.
toDec
()
private
Convert char to decimal value.
Properties
isReady
Boolean
Set to true when the IOBoard is ready. This can be used in place of listening for the IOBoardEvent.READY event when creating an app with a draw loop (such as when using processing.js or three.js);
samplingInterval
Number
Get or set the sampling interval (how often to run the main loop on the IOBoard). Normally the sampling interval should not be changed. Default = 19 (ms).
Events
analogData
BO.IOBoardEvent.ANALOG_DATA
The analogData event is dispatched when analog data is received from the IOBoard. Use thie event to be notified when any analog pin value changes. Use Pin.CHANGE to be notified when a specific pin value changes.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
pin
BO.PinA reference to the pin object.
digitalData
BO.IOBoardEvent.DIGITAL_DATA
The digitalData event is dispatched when digital data is received from the IOBoard. Use this event to be notified when any digital pin value changes. Use Pin.CHANGE to be notified when a specific pin value changes.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
pin
BO.PinA reference to the pin object.
firmwareName
BO.IOBoardEvent.FIRMWARE_NAME
deprecated
The firmwareName event is dispatched when the firmware name is received from the IOBoard.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
name
StringThe name of the firmware running on the IOBoard
-
version
NumberThe firmware version (where Firmata 2.3 = 23)
firmwareVersion
BO.IOBoardEvent.FIRMWARE_VERSION
The firmwareVersion event is dispatched when the firmware name and version is received from the IOBoard.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
version
NumberThe firmware version (where Firmata 2.3 = 23)
ioBoardConnected
BO.IOBoardEvent.CONNECTED
The ioBoardConnected event is dispatched when the websocket connection is established.
Event Payload:
-
target
IOBoardA reference to the IOBoard
ioBoardDisconnected
BO.IOBoardEvent.DISCONNECTED
The ioBoardDisconnected event is dispatched when the websocket connection is closed.
Event Payload:
-
target
IOBoardA reference to the IOBoard
ioBoardReady
BO.IOBoardEvent.READY
The ioBoardReady event is dispatched when the board is ready to send and receive commands.
Event Payload:
-
target
IOBoardA reference to the IOBoard
pinStateResponse
BO.IOBoardEvent.PIN_STATE_RESPONSE
The pinStateResponse event is dispatched when the results of a pin state query (via a call to: queryPinState()) is received.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
pin
BO.PinA reference to the pin object.
protocolVersion
BO.IOBoardEvent.PROTOCOL_VERSION
The protocolVersion event is dispatched when the Firmata protocol version is received from the IOBoard.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
version
NumberThe protocol version (where Firmata 2.3 = 23)
stringMessage
BO.IOBoardEvent.STRING_MESSAGE
The stringMessage event is dispatched when a string is received from the IOBoard.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
message
StringThe string message received from the IOBoard
sysexMessage
BO.IOBoardEvent.SYSEX_MESSAGE
The sysexMessage event is dispatched when a sysEx message is received from the IOBoard.
Event Payload:
-
target
IOBoardA reference to the IOBoard
-
message
ArrayThe sysEx data