Show:

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 String

    The host address of the web server.

  • port Number

    The port to connect to on the web server. Default = false.

  • protocol String

    [optional] The websockt protocol definition (if necessary).

Methods

addEventListener

(
  • type
  • listener
)

Parameters:

  • type String

    The event type

  • listener Function

    The 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:

Number: 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 Number

    The pin connected to the analog input

disableDigitalPins

()

Disables digital pin reporting for all digital pins.

dispatchEvent

(
  • type
  • optionalParams
)

Parameters:

  • type Event

    The Event object.

  • optionalParams Object

    Optional 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 Number

    The 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 Number

    The number of the input pin to enable the pull-up resistor.

getAnalogPin

() Pin

Returns:

Pin: A reference to the Pin object (mapped to the IOBoard board analog pin).

getAnalogPinCount

() Number

Returns:

Number: The total number of analog pins supported by this IOBoard

getDigitalPin

() Pin

Returns:

Pin: A reference to the Pin object (mapped to the IOBoard board digital pin).

getFirmwareName

() String deprecated

Defined in src/core/IOBoard.js:1120

Deprecated: use getFirmwareVersion instead

Returns:

String: The name of the firmware running on the IOBoard.

getFirmwareVersion

() String

Returns:

String: The version of the firmware running on the IOBoard.

getI2cPins

() Number private

Returns undefined if the board does not have i2c pins.

Returns:

Number: The pin numbers of the i2c pins if the board has i2c.

getPin

() Pin private

Returns:

Pin: 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:

Array: The capabilities of the Pins on the IOBoard.

getPinCount

() Number

Returns:

Number: Total number of pins

getPins

() Pin

Returns:

Pin: An array containing all pins on the IOBoard

getProtocolVersion

() String

Returns:

String: The version of Firmata protocol implemented by the firmware running on the IOBoard.

getSocket

() WSocketWrapper

Returns:

WSocketWrapper: A reference to the WebSocket

getValueFromTwo7bitBytes

(
  • lsb
  • msb
)
Number private

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 Number

    The least-significant byte of the 2 values to be concatentated

  • msb Number

    The most-significant byte of the 2 values to be concatenated

Returns:

Number: The result of merging the 2 bytes

hasEventListener

(
  • type
)

Parameters:

  • type String

    The 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
)
private

A websocket message has been received.

Parameters:

  • event Object

    The message property is an array of one or more stringified bytes from the board or a config string from the server.

parseInputMessage

(
  • data
)
private

Determine if the incoming data is a config message or a byte.

Parameters:

  • data String

    A 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
)
private

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 Number

    Digital 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 Number

    Bits 0 - 6 of the port value.

  • bits7_13 Number

    Bits 7 - 13 of the port value.

processInput

(
  • inputData
)
private

Process input data from the IOBoard.

Parameters:

  • inputData Number

    Number 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.PINSTATERESPONSE 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 Pin

    The pin object to query the pin state for.

removeEventListener

(
  • type
  • listener
)

Parameters:

  • type String

    The event type

  • listener Function

    The function to be called when the event is fired

reportCapabilities

() deprecated

Defined in src/core/IOBoard.js:1516

Deprecated: use reportPinCapabilities instead

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
)
private

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 Number

    Message data to be sent to the IOBoard

sendAnalogData

(
  • pin
)
private

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 Number

    The analog pin number. param {Number} value The value to send (0.0 to 1.0).

sendDigitalData

(
  • pin
  • value
)
private

Add the pin value to the appropriate digital port and send the updated digital port value.

Parameters:

  • pin Number

    The digital pin number.

  • value Number

    The value of the digital pin (0 or 1).

sendDigitalPort

(
  • portNumber
  • portData
)
private

Send the digital values for a port. Making this private for now.

Parameters:

  • portNumber Number

    The number of the port

  • portData Number

    A 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 Number

    Either Pin.On or Pin.OFF

sendExtendedAnalogData

(
  • pin
  • value
)
private

Sends an analog value > 14 bits and/or send a value for a pin number greater than 15.

Parameters:

  • pin Number

    The analog pin number (up to 128).

  • value Number

    The value to send (up to 16 bits).

sendOut

(
  • event
)
private

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 Event

    A 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 Number

    The 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
)
private

Send the servo angle.

Parameters:

  • pin Number

    The digital pin number the servo is attached to.

  • value Number

    The 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 String

    The string message to send to the IOBoard

sendSysex

(
  • command
  • data
)
private

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 Number

    The sysEx command value (see firmata.org)

  • data Number

    A packet of data representing the sysEx message to be sent

setAnalogPinReporting

(
  • pin
  • mode
)
private

Call this method to enable or disable analog input for the specified pin.

Parameters:

  • pin Number

    The pin connected to the analog input

  • mode Number

    Pin.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 Number

    The 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 Number

    Pin.DIN, Pin.INPUT_PULLUP, Pin.DOUT, Pin.PWM, Pin.SERVO, Pin.SHIFT, or Pin.I2c

  • silent Boolean

    [optional] Set to true to not send SETPINMODE command. Default = false.

setDigitalPinValue

(
  • pin
  • value
)

Set the value of the specified pin

Parameters:

  • pin Number

    The number of the digital pin.

  • value Number

    Pin.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 IOBoard

    A reference to the IOBoard

  • pin BO.Pin

    A 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 IOBoard

    A reference to the IOBoard

  • pin BO.Pin

    A reference to the pin object.

firmwareName

BO.IOBoardEvent.FIRMWARE_NAME deprecated

Defined in src/core/IOBoard.js:1575

Deprecated: use FIRMWARE_VERION instead

The firmwareName event is dispatched when the firmware name is received from the IOBoard.

Event Payload:

  • target IOBoard

    A reference to the IOBoard

  • name String

    The name of the firmware running on the IOBoard

  • version Number

    The 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 IOBoard

    A reference to the IOBoard

  • version Number

    The 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 IOBoard

    A reference to the IOBoard

ioBoardDisconnected

BO.IOBoardEvent.DISCONNECTED

The ioBoardDisconnected event is dispatched when the websocket connection is closed.

Event Payload:

  • target IOBoard

    A 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 IOBoard

    A 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 IOBoard

    A reference to the IOBoard

  • pin BO.Pin

    A 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 IOBoard

    A reference to the IOBoard

  • version Number

    The 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 IOBoard

    A reference to the IOBoard

  • message String

    The 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 IOBoard

    A reference to the IOBoard

  • message Array

    The sysEx data