Hack a robot weekend

Back in April of the last year (2020) I decided to 'hack' a small robot that I bought to teach some coding concepts to my daughter. The mobile app is great but I wanted to be able to use it on a computer, and surprisingly I wasn't able to find any software, library, or protocol documentation about it.

From the beginning, I thought about sharing the code so that anyone looking for the same thing could at least have it as a starting point.

But just now, after a year I remembered about this and wanted to clean up the code a little bit, publish it, and maybe write a blog about it.

Spying the communications

First of all, in order to be able to figure out the communication protocol I needed to 'Spy' the communications between the app and the robot. I tested different apps to spoof the Bluetooth communications on Android and iOS but without too much luck. I ended up using the PacketLogger from the XCode developer tools, it works like a charm and you can capture the Bluetooth communications in real-time from any app. (You have to install a log profile in your iPhone in order to get it working https://www.bluetooth.com/blog/a-new-way-to-debug-iosbluetooth-applications/)

After spying some packets the firsts patterns began to emerge

It is clear that all the packets sent from the app (Write Command) start with two fixed bytes 0xFB 0xBF and they end with the 0xED byte.

Figuring out the other parts of the protocol wasn't that easy or intuitive. I had to capture a lot of packets, some packets that I know must have the same fixed format. For example, move a specific motor. and knowing that only the parameters should change it had to be possible to discover the rest of the protocol.

The protocol

After many hours analyzing Bluetooth packets, I was able to figure out the packet format.

The Checksum is a simple sum of the payload (Length, Command, and the N parameters)

I found out that the responses are sent via events, and the number of responses depends on the command sent.

So I must send the command and wait for N responses but also add a timeout because, of course, something can go wrong.

The commands

Having already a packet format and a way to receive the responses the only pending thing was to discover the available commands.

The approach here was similar to the one I used with the communication protocol, make an action with the app on the robot many times in different ways to discover the commands and the parameters of them. Again, some of them were pretty easy to discover and others not that much.

So far I discovered commands to:

• Control the servo positions and speed
• Control the servo speed and direction (wheels)
• Stop wheels
• Control eyes colors
• Control eyes colors advanced (many colors per eye using a mask)
• Control eyes animations
• Read sensors
• Read servo positions

The code

I wrote a quick and dirt library to control the robot from node node-jimu
Here is the repository github.com/msantang78/node-jimu

Moving the robot:

Getting position and sensors data:

Controlling the robot's will

The audio output of the robot is just a Bluetooth speaker, so for this demo, I connected the computer to the robot speaker and used the node say library (https://www.npmjs.com/package/say)

In case you are interested in the code of this demo, you can check it out here