The Firmata Client is a Javascript class that runs in Node.js and communicates with the micro:bit Firmata firmware over a USB-serial connection. It implements the Firmata protocol and provides properties and methods for interacting with the micro:bit.
The Firmata Client communicates with the micro:bit via a serial port. The easiest way to open a connection is to call the connect() method, which looks for a serial port connected to a micro:bit and opens it.
- connect()
- Connect to the board. Scan all serial ports to find one with a micro:bit connected and opens that, if found.
- setSerialPort(port)
- Alternative to connect() that allows the client to supply an open serial port. Used by clients that do their own serial port management.
- disconnect()
- Close and discard the serial port. Seldom needed.
The following properties provide version information:
- boardVersion
- Property. The micro:bit hardware version (currently either 1.3 or 1.5).
- firmataVersion
- Property. Version of Firmata protocol used. Unlikely to change.
- firmwareVersion
- Property. Firmata firmware version. Includes DAL, mbed library, and soft device versions.
- buttonAPressed
buttonBPressed - Boolean properties. True while the given button is held down.
The buttons also generate events; see Event and Update Listeners.
The micro:bit display is a 5x5 LED matrix that can be used to display icons and to output text or numbers by scrolling them across the display. Icons can be binary (i.e. each LED is either on or off) or grayscale (i.e. each LED can have a brightness value from 0 to 255). Indidividual LED's can be controlled with the displayPlot() method.
- enableDisplay(enableFlag)
- Enable or disable the display. When the display is disabled, the edge connector pins normally used by the display can be used for other I/O functions. Re-enabling the display (even when is already enabled) disables the light sensor which, when running monopolizes the A/D converter preventing pins from being used for reliable analog input. Requesting a light sensor value restarts the light sensor.
- displayClear()
- Clear the display and stop any ongoing animation.
- displayShow(useGrayscale, pixels)
- Display the given 5x5 image on the display. If useGrayscale is true, pixel values are brightness values in the range 0-255. Otherwise, a zero pixel value means off and non-zero means on. Pixels is an Array of 5-element Arrays.
- displayPlot(x, y, brightness)
- Set the display pixel at x, y to the given brightness (0-255).
- scrollText(string, delay)
- Scroll the given text across the display. The optional delay parameter controls the scroll speed, with smaller numbers resulting in faster speeds. The default value is 120.
- scrollInteger(number, delay)
- Scroll the given integer across the display. The optional delay parameter controls the scroll speed, with smaller numbers resulting in faster speeds. The default value is 120.
- isScrolling
- Property. True while text is actively scrolling across the display.
- isScrolling
- Property. True while text is actively scrolling across the display.
Events are generated by micro:bit devices such as the buttons or accelerometer. An event is identified by a pair of integers, the DAL sourceID that identifies the device that triggered the event (e.g. button A) and the eventID (e.g. button down). These numbers can be found in the Message Bus section for each device in the DAL documentation
Event listener functions are called when an event is received, with the event sourceID and eventID as arguments.
Update listener functions are called when an analog channel or digital pin update arrives. It's up to that function to update any dependencies (e.g. to update the display when a sensor values has changed).
- addFirmataEventListener(eventListenerFunction)
- Add a listener function to handle micro:bit DAL events. The arguments of the function are the event sourceID and eventID (both numbers).
- addFirmataUpdateListener(updateListenerFunction)
- Add a listener function (with no arguments) called when sensor or pin updates arrive.
- removeAllFirmataListeners()
- Remove all event and update listeners. Used by test suite.
Button events are also generated by I/O pins 0-2 when they are configured to generate touch events by calling setTouchMode().
- setTouchMode(pinNum, touchModeOn)
- Turn touch mode on/off for a pin. Touch mode is only supported for pins 0-2). When touch mode is on for a pin,that pin generates events as if it were a button.
The micro:bit has 19 digitial I/O pins. The pins are numbered 0-20, but pins 16-17 are power pins, not I/O pins. Pins 0-2 have large round holes to allow easy connection using alligagor clips; the other pins are available via the edge-connector. Some of the edge-connector pins are also used by the display. Disable the display to use those pins.
To use a pin as a digital input, first call trackDigitalPin(). This will cause Firmata to send update events when the pin changes state. Note that the serial connection limits the speed at which such updates can arrive, so rapid states changes (i.e. more than about one state change per millisecond) cannot be tracked reliably.
- digitalInput
- Property. An array of 21 boolean values representing the current state of each pin.
- trackDigitalPin(pinNum, optionalMode)
- Start tracking the given pin as a digital input. The optional mode can be 0 (no pullup or pulldown), 1 (pullup resistor), or 2 (pulldown resistor). It defaults to 0.
- stopTrackingDigitalPins()
- Stop tracking all pins as digital inputs.
- setPinMode(pinNum, mode)
- Set the given pin to one of the Firmata pin mode constants: DIGITAL_INPUT, INPUT_PULLUP, INPUT_PULLDOWN, DIGITAL_OUTPUT, ANALOG_INPUT, or PWM.
Firmata supports streaming of up to 16 channels of analog data at a sampling rate determined by the client. Analog data can be streamed from any combination of the micro:bit's six input pins and its built-in sensors (e.g. accelerometer).
- analogChannel
- Property. Array containing the latest value of each channel being streamed. The client can register an update function to be notified when new channel data has arrived.
- clearChannelData()
- Reset all analog channel entries to zero.
- streamAnalogChannel(chan)
- Start streaming the given analog channel.
- stopStreamingAnalogChannel(chan)
- Stop streaming the given analog channel.
- setAnalogSamplingInterval(samplingMSecs)
- Set the number of milliseconds between analog channel updates (1-16383). Defaults to 100 milliseconds (10 updates/sec) when Firmata is started.
- enableLightSensor()
- Enable the light sensor. (Note: When running, the light sensor monopolizes the A/D converter, preventing use of the analog input pins, so the light sensor is disabled by default. This method can be used to enable it.)
- setDigitalOutput(pinNum, turnOn)
- Make the given pin an output and turn it off (0 volts) or on (3.3 volts) based on the boolean turnOn parameter. This can be used, for example, to turn an LED on or off.
- setAnalogOutput(pinNum, level)
- Start outputing a simulated analog voltage level on the given pin, where level (0-1023) maps to a simulated voltage of 0 to 3.3 volts. Since micro:bit pins can only be on or off, the voltage level is simulated using "pulse width modulation" (PWM). That is, the pin is turned and off rapidly, using the level to determine what fraction of time the pin is on. PWM can be used, for example, to control the brightness of an LED.
- turnOffOutput(pinNum)
- Turn off either the digital or analog output of the given pin. (The pin reverts to being an input pin with no pullup.)