Bitty Controller Common Information

The General Approach

Bitty Controller sends data to the device it is connected to over Bluetooth to indicate something the user just did such as pressing or releasing one of the pads in the D-Pad controller user interface (UI) or sliding the trackball up the touchpad with a finger. These data values are known as Events and each has a unique ID, a number which indicates what type of event it is and therefore what type of user action it is indicating took place. It is then up to the code on the micro:bit to decide what to do with the events it receives. Perhaps a motor will be started or a light flashed. Note that events also have a value as well as an identifier. Sometimes the value is significant and used and other times it is not.

Bitty Controller's on/off switches UI works slightly differently. We'll come to that shortly.

Writing code for a micro:bit to respond to Bitty Controller events falls into two parts therefore.

1. Communication between Bitty Controller and the micro:bit

Bitty Controller uses the same types of events for the various user interactions that are possible with the various user interface choices that Bitty Controller offers and so some of the micro:bit code for a Bitty Controller project which uses a particular one of the UIs will always be the same, irrespective of what it is that is being controlled.

micro:bit code will need to ensure that it receives events of the types that are of interest and then use appropriate logic to initiate required responses to those events.

2. Controlling things physically connected to the micro:bit

Having determined what it is that the user just did, by examining event IDs and values, the micro:bit code will need to perform some kind of action to instigate the required type of control. Maybe this means rotating a servo through 90 degrees. Maybe it means speeding a motor up to full speed. Or maybe it means flashing a series of LEDs. It could mean anything and this is where you, the micro:bit developer will need to know what it is that you want to do and how to go about accomplishing it with the micro:bit C/C++ APIs or MakeCode blocks. This may require you to have some information about your device such as which micro:bit pins its motors are connected to.

The Bitty Controller example code here at bittysoftware.com is a good source of information on the details of controlling a variety of popular bots and other maker kits.

Bitty Controller UIs and Events

The event IDs and values used by the various UI types are documented here.

D-Pad Controller UI


Event ID Event Value Explanation
1104 1 Button A was pressed
1104 2 Button A was released
1104 3 Button B was pressed
1104 4 Button B was released
1104 5 Button C was pressed
1104 6 Button C was released
1104 7 Button D was pressed
1104 8 Button D was released
1104 9 Button 1 was pressed
1104 10 Button 1 was released
1104 11 Button 2 was pressed
1104 12 Button 2 was released
1104 13 Button 3 was pressed
1104 14 Button 3 was released
1104 15 Button 4 was pressed
1104 16 Button 4 was released

Touchpad Controller UI


Sliding the trackball results in an event with ID 9011 being transmitted. The associated 16-bit value encodes two pieces of information of 8-bits each. The first indicates how much up or down the touchpad the trackball was pushed, in the range -10 to +10 where -10 is the bottom of the touchpad and the second indicates how much left or right of the vertical centre line the ball was pushed, again in the range -10 to +10. From these values, micro:bit code can do things like choose the direction of motors and their speed. Typically the further from the centre the trackball has been pushed, in some direction, the faster we want appropriate motors to go!

Here are some examples. Note that values are shown in hexadecimal since this makes it easier to see the two parts representing vertical displacement of the trackball from the centre point and horizontal displacement. And just to add to the fun, as is the norm, negative numbers are represented using two's compliment. If this means nothing to you, you'll need to do some reading on the subject.

Event ID Event Value Explanation
9011 0x0000 Vertical and horizontal displacement are both zero so the trackball is at the centre.
9011 0x0A00 Vertical displacement is +10 and horizontal displacement is 0 so the trackball has been moved to the very top of the touchpad but with no left or right movement.
9011 0xF600 Vertical displacement is -10 and horizontal displacement is 0 so the trackball has been moved to the very bottom of the touchpad but with no left or right movement.
9011 0x070A Vertical displacement is +7 and horizontal displacement is +10 so the trackball has been moved upwards but is not quite at the very top of the touchpad. It's also been moved to the very right of the rouchpad, perhaps indicating a hard right turn in the forwards direction is required.
9011 0xFBFC Vertical displacement is -5 and horizontal displacement is -4 so the trackball has been moved towards the bottom of the touchpad and some way over to the left, perhaps indicating the machine under control should reverse and turn to the left relatively slowly.

Sensor and other data from the micro:bit


The enhanced touchpad UI includes a number of spaces for data sent from the micro:bit to be displayed, possibly after being transformed using a function you can specify in Bitty Controller's Options screen. So in this case it is the micro:bit code which is creating events and Bitty Controller which is receiving and processing them.

Typically this data will come from micro:bit's sensors but it could come from anywhere, including from devices electrically connected to the micro:bit's edge connector or simply calculated in some way from within your code. In descriptions, it's usually assumed that sensors are involved though.

To instruct the micro:bit code to start reading sensor values, Bitty Controller will send a "SAMPLING_START" event to the micro:bit. When this event is received, your code should start acquiring data values, perhaps in a loop and sending them to Bitty Controller. All you need to do to accomplish the latter is to create a micro:bit event with the right ID.

In summary, these are the event types involved with the sending of data from a micro:bit to Bitty Controller's enhanced touchpad UI:

Event ID Event Value Explanation
9014 sensor # and value The value part of this event type contains two pieces of information, encoded within its 16 bits. Bits 0-9 contain a sensor value and bits 10-12 contain a sensor no or some other numeric identifier in the range 1-5. It is this which determines which of the sensor value fields in the UI, the value is displayed in. The two pieces of data are combined into the 16-bit value field using left shift bitwise logic. See example below.
9015 N/A Instructs the micro:bit code to start acquiring sensor data and sending it to Bitty Controller.

Example code fragments:

Event IDs
    SENSOR_VALUE = 9014
    SAMPLING_START = 9015
Transmitting a sensor reading as an event
    function transmitSensorValue() {
        // bits 0-9 contain value. Bits 10-12 contain a sensor no.
        ev = (sensor_no << 10) + the_sensor_value
        control.raiseEvent(
            SENSOR_VALUE,
            ev
        )
    }            
Listening for SAMPLING_START events
    control.onEvent(SAMPLING_START, 0, sampleSensors)
Handling SAMPLING_START events
    function sampleSensors() {
        sampling_sensors = 1
        temperature = 0
        while (sampling_sensors == 1) {
            // read the internal thermometer
            temperature = input.temperature()
            // assume min temperature of -20 and max of +40
            // (adjust to suit your purposes) and transform to the
            // required range of 0-1023 range is 60
            temperature = Math.round((temperature + 20) / 60 * 1023)
            // transmit events over Bluetooth
            sensor_no = 5
            the_sensor_value = temperature
            transmitSensorValue()
            basic.pause(250)
        }
    }

The multipad buttons


The touchpad with multipad buttons UI allows events to be sent to your micro:bit whenever one of the buttons in the UI is pressed. You can then respond to them in any way you want. Each button is numbered from 1 - 12 and you choose which buttons are enabled and visible in the UI from within the Options screen. In your micro:bit code you register for the event type associated with the multipad buttons and then check the value part of any event which you receive to decide what action to take.

Event ID Event Value Explanation
9016 buttn # The value part of this event type contains the numeric identifier of the button pressed in the range 1-12.
    MULTIPAD_CONTROL = 9016
    control.onEvent(MULTIPAD_CONTROL, EventBusValue.MICROBIT_EVT_ANY, onMultipadEvent)

    function onMultipadEvent() {
        if (control.eventValue() == 1) {
            shakeHead();
        }
        if (control.eventValue() == 2) {
            wagTail();
        }
        if (control.eventValue() == 5) {
            eyesOn();
        }
        if (control.eventValue() == 6) {
            eyesOff();
        }
    }
            
        

Bitty Controller and the On/Off Switches UI


The on/off switches UI does not use events to communicate with your micro:bit. Instead, the Bluetooth capabilities of a micro:bit includes something called the IO Pin Service. With this component included in your code, that's all you need to do. Bitty Controller communicates directly with this software component to tell it what to do with particular pins such as switching pin 1 on and pin 5 off.

Here's all you need in a MakeCode project to ensure this works: