The Emerald M3D serial format

Want to write your own software to talk to the Emerald?

NOTE: If I blow up my engine, it's my fault. It's not my fault if you blow yours up...

I've got a pet project which I haven't got round to playing with properly yet, but it relies on being able to read data in real-time from the Emerald M3D ECU in my Seven. These pages document my attempts to figure out how to do that, since I've had a few questions asking about how I am getting on.

Background

When you run the Emerald software, the only thing connecting the PC to the Emerald is the serial lead. And it works when it goes through a serial-to-USB converter, so it can't be playing any nasty tricks, so my first thought was to just run the Windows Terminal program, cross my fingers, and hope that the Emerald just spat out data without requiring any special handshaking from the PC. After a bit of trial and error I found out that it was expecting to talk at 19200 bps, with 1 stop bit, no parity, and an 8-bit data word. Luckily it was indeed very chatty, so I captured the output for later analysis.

Fortunately the Emerald guys have been as open with their data as they have with much other information about the M3D. Although the format is not published, they have used standard codes for some important things. The first thing I noticed is that there were some patterns of standard ASCII characters, like a sequence of numbers counting up, "1", "2", "3", etc., surrounded by characters with values less than 32. The old ASCII control codes are all lesss than 32, so I dug out a table, and it all started to make sense.

An overview of the data format

There are several different types of Emerald data block, but they all have a similar format. First comes SOH (Start of Header, ASCII 0x01 - the "0x" means that the value is being written in hexadecimal). The next three characters are a code identifying the type of block which is about to be sent (e.g. "spS" - no, I don't know what it stands for, but I think the first two characters identify the block and then the "S" means "Start").

Then comes the actual data. Each block type has a fixed number of data items, but the number varies between block types. Each data item is RS (Record Separator, ASCII 0x1E), followed by the record identifier (e.g. "0" (0x30) is the first record of the block), then several characters representing the data in hexadecimal. For example, a data item which was a single byte with a value of 255 would be sent as 0x1E, "0", "FF". Again, the number of characters in a record varies between records, but is always the same for a particular record of a particular block (so far I have seen 2, 4, or 8 hex digits in a record).

At the end of the block is EOT (End of Transmission, ASCII 0x04), followed a code identifying the end of that particular type of block. For example, the close to an "spS" block is "SPe". (I think the general rule is that the first two characters are the same as in the SOH string, but of the opposite case, followed by "e").

The pattern then gets repeated, possibly with a different kind of block.

Incidentally, SciTE is a very useful text editor, and it highlights ASCII control codes like in the picture above.

The data blocks in detail

The blocks I have identified so far are:

I didn't just stumble on the $c$s thing... When I ran the Emerald software in live mode it was showing me data that I hadn't been able to identify in the blocks I had seen in captured logs. So I used the free PortMon tool to watch the serial port whilst running the Emerald software, and I noticed that it sent the "$c$s" string. Great tool.



This page is http://www.strangely.org/emerald/format.html. It was first published on Thursday 2 December, 2004 and last updated on Thursday 2 December, 2004.