Reverse Engineering the RVR Protocol

I have started a Wiki that records my work on reverse engineering the protocol. There are some code snippets in the documentation.

It is on BitBucket where I’ll eventually put a C++ implementation in a repository. I’ll update code when the final specification is available.

It would be nice if this thread consolidated the information people glean from code or we obtain from Sphero.

You’ll notice in the Wiki I’ve included information that I have not tested or implemented. Also areas where I’ve seen hints but don’t know details. If you can elaborate on any of this please comment in reply and I’ll add the information. As I implement items I’ll remove the tentative indicators.


I’m a Github newb. Would it make sense to work on a Wiki that they can pull?

1 Like

That’s a great idea. I wonder if it would make sense to try to document it in some kind of language-neutral format such as kaitai struct? (I haven’t used this, but it looks cool and there is support for a lot of different languages, which might make it more general than just C++.)

I’m still in the very early hooking-up-the-hardware stage but would definitely like to help once I’m a bit farther along.

1 Like

You will be able to pull the Wiki but don’t know why you would.

1 Like

The Wiki will be general with only a few code snippets.

1 Like

Looks like most of their SDKs may have been made using this toolkit and a set of templates

Raspberry Pi NodeJS was created using this file it looks like.

Not sure if Sphero will be willing to provide that file for the raw API, but when they release the API, we could make our own, or use a different tool that does the same thing if needed

1 Like

I believe that’s the definition for the REST API (eg, web access). @rmerriam is talking about documenting the wire protocol over the serial port to the RVR itself. Presumably the web server also implements this protocol, so there should be ample documentation between it and the python API.

1 Like

So they can have their info in as centralized a place as possible.

1 Like

I have many of the commands working. The Wiki is coming along but some of the pages are just raw information copied from the Pi SDK. Will get those better documented soon.

One command set working is for LEDs. I can’t get the undercarriage white LED to work. It is functional because using the Edu app it turns on.

Here’s the message I’m sending and the response:

8D 12 1 1A 1A 82 40 0 0 0 FF F7 D8 

cnt: 9
8D 21 1 1A 1A 82 4 23 D8 

That’s following the pattern that each LED bit set requires a color byte for it. Tried adding 3 bytes of color but doesn’t work.

Is there any documentation for the error codes in responses?

Code is still raw in a few places but should get it cleaned up in the next day or so and release it to public access.


I was just looking through what you’ve started in the wiki, great work so far! Are you planning to also dig into controlling IR transmission and reception?

1 Like

I have posted some very alpha-release code to Github:

It’s a start… the “rvrio.c” forms the basis for sending to and receiving from the RVR. Note logging, which helps debug problems.

I am very open to changes and updates and improvements. I want this code for teaching my class next semester, so making as good as possible is in my best interest.


Probably won’t do much with the IR since I have only a single unit. That makes it a challenge to assure it works properly plus no motivation. The code base should make it easy for someone to add that capability.


Just realized my code repository is public. It’s at Protocol documentation is in the Wiki which you can access through the left sidebar at that URL. Will add some commentary to the code Read Me about how the code is currently (un)organized. (There is a quirky sense to it but driven by the experimental nature of this work instead of formal development. It will get better.)

There is a lot of working code:

  • Power
  • Led
  • API
  • SysInfo
  • Connection

The transport or packet sending is complete, as far as I can tell. Currently working on parsing responses since that is necessary for receiving the sensor data. That also gets into multi-threading to be effective so there are some ‘tricks’ needed for them.

Let me know if you see anything strange. I’ve enabled Issues so you can comment or ask questions. This is developing as I go so consider it a moving target with possible changes at any time.


Now that I’ve made some good progress on reverse engineering the protocol for C++ I need to start working on the overall system perspective for using the RVR. My target is to use the Robot Operating System (ROS) on the Up Board shown in another message. So I drew some diagrams to keep me focused. Current versions are in my Wiki. They are not technically correct UML but suit my purpose.


Status Update

Have all the requests and responses working for ApiShell, Drive, LEDs, Connection, Power and direct reading of Sensors. I split sensors to separate the handling of direct and streaming. Hoping streaming won’t take long since it should be a lot of similar code with just variations for the type of sensor. (Famous last words.)

Not going to implement the Sensor infrared messages or the LED color pallet and color messages since they don’t interest me.

Have not updated the Wiki recently but it doesn’t discuss the code very much.

Took 3 revisions to the data dictionary format and handling of responses to get here. Streaming may require another change but hope not.

Also have a major change to make impacting all the sensor classes on how the dictionary, or blackboard, is handled.

Really want to wrap this part up so I can move to writing ROS drivers.


Amazing work! What are you using to draw up the architecture diagrams?

1 Like

Diagrams are done with Visual Paradigm.