I like Bruce McGee's answers. Having worked with similar interfaces I can offer several other pointers:
When returning numeric types in a data packet, please please PLEASE try to make everything the same format. Don't have single for some numbers and double for others. And don't make it arbitrary!
Provide examples for data packets in your ICD. It's terribly frustrating to have to guess at byte order or even bit order (is MSByte first, or last? What is first and last?). Provide a diagram that shows packets vs. time (ie, 0x02 is sent earliest, then the address byte, then the message id, etc).
Don't switch around between data formats if at all possible. I've worked in systems that use 'ASCII-encoded numbers' for some messages where you have to strip the leading '3' off of the bytes, then pull them together to make the real number. (Usually ASCII-encoding is used when you have a byte sequence you have to avoid, like 0x02, 0x04, etc. Encoded the numbers would be 0x30, 0x32, 0x30, 0x34. Use a length field if possible to avoid this, or at least do it all the time!)
Definitely definitely definitely document the baud rate, parity, etc. If you're using RS-485 document the bus mode (2-wire? 4-wire?) or whatever settings will appear on the machine that you intend this to be used on. Give screenshots if you have to.
This interface will probably be very useful for debug. I've worked with some systems that had debug features such as:
A system where the programmer made a list of 'logged parameters' (internal variables). You would tell the system which ones you wanted reported (up to 8) and then when you queried the system for the logged parameters it would return them in one data packet. I liked this, but depending on the complexity of the system you may or may not be able to specify them at run-time (or you could do something simple and send the system a mask that would select the ones you want returned).
Data packets that 'break' behavior
and allow parts of the system to be
tested independently (ie, on a D/A put out this voltage, on a DIO port stim this byte, etc)
Good luck!
