Android-Firmata

IoT Library for Android Developers. Inspired by Johnny-Five.

Android-Firmata is a client library of Firmata written in Kotlin. It allows controlling Arduino (or other boards, such as NodeMcu...) which runs Firmata Protocol from your Android Application.

^{🙈 WALL·E and my GUINEA PIG 🙉}

Benefits

• Easy Peripherals with Kotlin Programming Language

• Easy Remote Controling with Android UI Components and Android Animator API

• Compatible with Android Things (Control Arduino Boards form Android Things)

Installation

In your build.gradle:

dependencies {
    implementation 'com.xujiaao.android:android-firmata:${android_firmata_version}'
}

Get Started

The ubiquitous "Hello World" program of the microcontroller is "Blink an LED". The following code demonstrates how this is done using the Android-Firmata Library.

class GetStartedActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        /**
         * Connect board through Bluetooth transport.
         *
         * NOTICE: Make sure the name of Bluetooth device is "HC-06",
         * and the device has already been bonded with your Android phone!!!
         */
        connectBoardWithLifecycle("bt://HC-06".toTransport(this), lifecycle, {
            onConnecting { toast("Connecting...") }

            onConnected { board ->
                toast("Connected")

                val led = board.Led(13) // Create an Led on pin 13
                led.blink(500) // Blink every half second
            }

            onDisconnected { error ->
                if (error != null) {
                    toast("Disconnected: ${error.message}")
                }
            }
        })
    }
}

Note: The image above is copied from Johnny-Five.

Guidance

Before programing with the Android-Firmata Library, you need to select in which way your Android Device and the Arduino Board being connected.

Currently, these communication modes are supported:

• Connect via Bluetooth

• Connect via WiFi

• Connect via USB

---

Connect via Bluetooth

Requirements

• StandardFirmataPlus v2.5.0 or greater

  • Arduino IDE > Examples > Firmata > StandardFirmataPlus

• A Bluetooth Serial Port Module (such as HC-05, HC-06):

  

Setup the Bluetooth Serial Port Module

Since Firmata runs at 57600 baud, you'll need to configure the module before making a connection with Android-Firmata.

Check out the Johnny-Five Bluetooth Guide for more information.

Android Programing

Update the Transport URI in your Android Application to let it know which device should be connected.

For Bluetooth Connection, the URI can be either of:

• bt://<bluetooth_name> (Matches the Bluetooth Name)

  • Make sure the Bluetooth device has been bonded before connecting

• bt://<bluetooth_mac_address> (Matches the Bluetooth Mac Address)

  • Please replace the : in your Mac Address with . or - (e.g. bt://00.11.22.33.44.55)

• bt://<bluetooth_mac_address>?pin=<pin> (For Android Things, Pairs with the Pin)

  • Please replace the : in your Mac Address with . or - (e.g. bt://00.11.22.33.44.55?pin=1234)

For example:

/**
 * If the name of your Bluetooth device is "HC-06", then the URI should be:
 *
 *   "bt://HC-06"
 */
connectBoard("bt://HC-06".toTransport(context), ...)

---

Connect via WiFi

Requirements

• StandardFirmataWiFi v2.5.0 or greater

  • Arduino IDE > Examples > Firmata > StandardFirmataWiFi

• A NodeMcu (ESP8266) Board

  

Setup NodeMcu

Check out the NodeMcu Guide to learn about how to install StandardFirmataWiFi on the board.

Android Programing

For WiFi Connection, the Transport URI is:

• tcp://<board_ip_address>:<board_port>

For example:

/**
 * If the ip address is '192.168.4.1', and the port is '3030', then the URI should be:
 *
 *   "tcp://192.168.4.1"
 */
connectBoard("tcp://192.168.4.1".toTransport(context), ...)

---

Connect via USB

Requirements

• StandardFirmataPlus v2.5.0 or greater

  • Arduino IDE > Examples > Firmata > StandardFirmataPlus

• An Android Phone which supports OTG

• An USB Host Cable

  

Android Programing

For USB Connection, the Transport URI is:

• usb (Selects the First Supported USB Device)

• usb:/<device_name> (Selects the USB Device with the Specified Device Name)

  • For example: usb:/dev/bus/usb/001/006

Note: USB Transport is based on FelHR85's UsbSerial Library.

Documentation

Transports

Android-Firmata Library uses a Transport URI to identify how devices are being connected:

• Bluetooth:

  • bt://<bluetooth_name> (Matches the Bluetooth Name)

    • Make sure the Bluetooth device has been bonded before connecting

  • bt://<bluetooth_mac_address> (Matches the Bluetooth Mac Address)

    • Please replace the : in your Mac Address with . or - (e.g. bt://00.11.22.33.44.55)

  • bt://<bluetooth_mac_address>?pin=<pin> (For Android Things, Pairs with the Pin)

    • Please replace the : in your Mac Address with . or - (e.g. bt://00.11.22.33.44.55?pin=1234)

• WiFi:

  • tcp://<board_ip_address>:<board_port>

• USB:

  • usb (Selects the First Supported USB Device)

  • usb:/<device_name> (Selects the USB Device with the Specified Device Name)

    • For example: usb:/dev/bus/usb/001/006

Sample Application (:link: Link)

Android-Firmata provides a Sample Application, it shows how to control peripheral devices with Android-Firmata.

Note: Images in the sample application are copied from Johnny-Five Examples Page.

Usage

• Download and install the Sample Application on your Android Device.

• Select a smaple

• Follow the breadboard image in the Sample Page for wiring

• Click the "Connect/Disconnect" button in the top right corner to connect your board

• To edit the Transport URI, open the "Settings Menu" in the Home Page, select "Transport"

If you want to run the Sample Application on Android Things, try Vysor.

TODOs

• Support BLE transport

License

Android-Firmata is distributed under the terms of the MIT License. See the LICENSE file.