MrlComm and the importance of Auto-generated Code

Ahoy !

When you have maintain the same message structures with different languages, it sometimes is advantageous to GENERATE CODE ! rather than write it.

MrlComm has messages we want to be encoded and decoded in both Java & Arduino C++, and perhaps more languages or encodings.

So we make "One Document To Control It All" -> arduinoMsgs.schema

This file documents all messages to and from the Arduino in our binary protocol. This file controls the messaging and serialization between Arduino MrlComm library and MRL's Arduino Java Service. It does this by generating code which calls appropriate messages after serializing and deserializing data over the serial COM line. That way developers only need to worry about the business logic in MrlComm or their MrlDevice, and all the nitty gritty dirty and boring business of remote procedure calls and data-type conversion is left to the generated code.

Because Different Languages have different datatypes our schema document must be able to translate. Here is the table of conversions and the keywords for our document.

Schema	Arduino C++	Java	Range
(none)	byte/unsigned char	int (cuz Java bytes bite!)	0 to 255
boolean	boolean	boolean	0 to 1
b16	int	int (short)	2 bytes -32,768 to 32,767
b32	long	int	4 bytes -2,147,483,648 to 2,147,483,647
bu32	unsigned long	long	0 to 4,294,967,295
float	float 4 bytes	float	3.4028235E+38 to -3.4028235E+38
str	char*, size	String	variable length
[]	byte[], size	int[]	variable length

And here is the beginning of the message definitions in arduinoMsgs.schema

# Arduino Diagnostics and Status

< publishMRLCommError/str errorMsg

> getBoardInfo

< publishBoardInfo/version/boardType/b16 microsPerLoop/b16 sram/activePins/[] deviceSummary

# removed - for simplicity, merged data into BoardInfo

# < publishBoardStatus/b16 microsPerLoop/b16 sram/[] deviceSummary

# > enableBoardInfo/bool enabled # simplified - just goes to Arduino-Javaland now

> enablePin/address/type/b16 rate

> setDebug/bool enabled

> setSerialRate/b32 rate

> softReset

As you probably can guess :
# is a comment,
> is a message which goes from the Service to the Arduino board
< is a message which is sent from the Arduino board to the Service

> getBoardInfo is a message from the Service request information from the board

< publishBoardInfo/version/boardType/b16 microsPerLoop/b16 sram/activePins/[] deviceSummary

is a response from the board with many types of data, first its version (1 byte), then the boardType (1 byte), then microsPerLoop (a 2 byte int), memory (2 bytes), activePins (1 byte), then device summary - which is an array of bytes.

If we want to add another message we simply, add the new line and definition of a message to this file, and run the ArduinoMsgGenerator. The ArduinoMsgGenerator reads this file, and creates the additional code.

Moz4r was interested in adding the Arduino's analogReference(type) to the messages. I noticed he called it setAref(type) ... usually I like to use the same name of the method (ie analogReference) all the way through for transparency, but he probably already has code which relies on this name.

so I appended the following ot the end of arduinoMsgs.schema

# set ARef

> setAref/b16 type

And also changed static final Integer MRLCOMM_VERSION = 55; in ArduinoMsgGenerator from 55 to 56

This generated all the necessary code, and increments the necessary parts. Moz4r already add the method in the Arduino Java service to utilize it.

I noticed, after code generation there was an error in the VirtualArduino. It looked like the setAref method was copied from Arduino. I don't think it should be there, VirtualArduino mimics the actual board not the service. So this function does not belong here. What should happen is the aref variable should affect arduino reads in some way (not sure of the details). Anyway, I commented it out.

In the future for transparency and clarity I would change setAref's name to analogReference, but since this is a "real" keyword there is one more thing which needs to be done.

In ArduinoMsgGenerator - you'd need to add it to the keyword map. The generator will do the "right" thing - which is just to call the function.

ArduinoMsgGenerator() {
    // add your keywords
    keywords.add("pinMode");
    keywords.add("digitalWrite");
    keywords.add("analogWrite");
    keywords.add("analogReference");

References :

Wahoo thank for your review

Wahoo thank for your review and those precious informations. I was thinking arduinoMsgs.schema was a documentation file. Now I understand. I think I I took the computer's job :)