proposal: add package to allow controlling BuWizz batteries

[kortschak]

The BuWizz battery is a promising device that allows control of LEGO motors and other power functions by Bluetooth. It can be controlled (currently) via an app available for ios and android.

The developers claim that the communication protocol will be opened. However, there is little indication that this is happening. When it does, add a package that allows a BT-enabled EV3 device to control paired BuWizz bricks.

[kortschak]

The situation remains difficult here. There continues to be very little communication from the manufacturer, even commented on at the kickstarter comments page.

I have started working on reverse engineering the protocol.

[kortschak]

The BuWizz provides three GATT services, two standard and one that appears to do the work that we want.

Quick scan with nRF:

Generic Access
UUID: 0x1800
Primary service

        Device name
        UUID:       0x2a00
        Properties: READ
        Value:      HMSoft

        Appearance
        UUID:       0x2a01
        Properties: READ
        Value:      [0]

        Peripheral privacy flag
        UUID:       0x2a02
        Properties: READ,WRITE
        Value:      Privacy disabled

        Reconnection address
        UUID:       0x2a03
        Properties: READ,WRITE
        Value:      00:00:00:00:00:00

        Peripheral preferred connection parameters
        UUID:       0x2a04
        Properties: READ
        Value:      Connection interval:            100.00ms - 200.00ms
                    Slave latency:                  0
                    Supervision timeout multiplier: 1000

Generic attribute
UUID: 0x1801
Primary service

        Service changed
        UUID:       0x2a05
        Properties: INDICATE

        Descriptors:
        Client characteristic config
        UUID:       0x2902

Unknown service
UUID: 0x0000ffe0-0000-1000-8000-00805f9b34fb
Primary service

        Unknown characteristic
        UUID:       0x0000ffe1-0000-1000-8000-00805f9b34fb
        Properties: NOTIFY,READ,WRITE
        Value:      0x00

        Descriptors:
        Client characteristic config
        UUID:       0x2902
        Characteristic user description
        UUID:       0x2901

Writing to handle 0x12 appears to control the battery.

The written value looks like this:

+--------+--------+--------+--------+--------+
|1aaaaaaa|0bbbbbbb|0ccccccc|0ddddddd|0pp00000|
+--------+--------+--------+--------+--------+

Where a, b, c and d are 7-bit signed integers for the port output level, and p is the overall power level - the lower bit being on for normal, the high bit being on for high power and both bits off for low power (0x00=low, 0x20=normal, 0x40=high).

The first bit in the value always appears to be set and I have seen no non-zero states for all the bits marked 0.

Reading from 0x12 gives a nearly monotonically increasing value that may reflect battery power in some way.

[kortschak]

I can confirm the above with experiments using gatttool with the following additions:

1. The bits of the pp field in the fifth byte is additive, so it is actually a 2-bit range of power outputs, not just two modes - 0x60 runs a motor a fair bit faster than 0x40. This may be their "ludicrous" mode.
2. The notification on 0x12, e.g. 98 51 00 00 00 00 00 69 00 06 reflects a few characteristics: the second byte changes when a port is turned on, generally sitting at 0x52, but dropping transiently to ~0x4e before rising again (usually - on occasion it has risen).
3. Writing to the 0x12 handle only causes a transient output from the battery - it looks like about 2.5s. Writing a zero to the relevant byte will immediately turn off the power output.

These are demonstrated here:

Notification handle = 0x0012 value: 98 52 00 00 00 00 00 66 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 64 00 06 
[5C:F8:21:xx:xx:xx][LE]> char-write-req 0x0012 80003f0040
Characteristic value was written successfully
Notification handle = 0x0012 value: 98 51 00 00 00 00 00 66 00 06 
Notification handle = 0x0012 value: 98 4e 00 00 00 16 00 65 00 06 
Notification handle = 0x0012 value: 98 51 00 00 00 02 00 64 00 06 
Notification handle = 0x0012 value: 98 51 00 00 00 01 00 65 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 66 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 66 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 66 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 66 00 06 
Notification handle = 0x0012 value: 98 51 00 00 00 00 00 64 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 64 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 65 00 06 
Notification handle = 0x0012 value: 98 52 00 00 00 00 00 65 00 06 

A guess at the notification's second byte's significance would be voltage drop over the battery since it spikes downwards with turning on the motor and does not vary depending on the sign of the 7-bit value (which does change the motor direction as expected).

A guess at the fourth to seventh bytes' significances would be power draw since they peak on start and then stay low but non-zero if the battery is repeatedly written to to keep a motor running.

The eigth byte appears to indicate temperature - placing the battery next to the fan output of the laptop increases the value and chilling the battery briefly in the fridge reduces it. (This explains the near monotonic increase observed previously since that survey was just starting the use the battery and so it was warming).

The first byte (and second) change when a USB cable is plugged into the battery, in the case above to f8 54 and for another battery f8 72 (from b8 70), so it looks like both those bytes are the battery's charge, bigendian.

The third, ninth and tenth bytes remain a mystery.

+===+===+===+===+===+===+===+===+===+===+
|   V?  | ? | p1| p2| p3| p4| T | ? | ? |
+===+===+===+===+===+===+===+===+===+===+