python interface

Hey Michael!

I haven't had a chance to document the serial protocol yet, as it's the hardest part of the documentation *grin* The serial com pde file is probably the best location, as the comments at the beginning of the PDE detail every aspect of the serial protocol. However, as data is sent in a native format (e.g. two bytes represent a 16 bit number, rather than trying to express the data as a series of ascii character bytes), it will help to look at the perl code, as both perl and python use a pack() function. (Although in python it's struct.pack(), IIRC.) While you'd have to convert the perl templates to python templates, they would be highly instructive. Just look for pack() in a given function in the perl code.

A key point is that all data used is big-endian, don't use little-endian pack templates. =)

I haven't started on a GUI yet, and would love it if you did - that would be great!

!c

Michael,

The first byte is actually a 'primary' command. There are two primary commands supported right now, 'program control' [1] and 'set program data' [2] (aka 'configure'). You can look at it this way: a program control command will result in something happening immediately, and a set program data will change some operating parameter of your current program in the engine. (e.g.: how far motor 1 should move between shots, what actions are available, which keyframes are set, how often to fire the camera, etc.)

The data length to be transmitted is the second byte, so the protocol supports up to 255 total data bytes for a given primary command, although I don't think we'd ever use that =). The important part about this one, is it is the length of bytes AFTER the first two. Never include the first two (primary command and data length bytes) in the data length value.

The third byte is the secondary command.

So, for example, to start the program running, I would send three bytes:

111 (as B00000001 B00000001 B00000001 - binary '1', unsigned char or byte value in arduino world)

Primary command: Program Control
Data Length: 1 byte
Secondary Command: Start

Now, you may ask "what do I do when there's data corruption and I don't complete my command?" The engine will wait until it receives all of the bytes you told it you'd send. I had originally built in a time-out function into the serial code, but that took another 64 bytes of memory for the counter alone, and I thought that un-frugal when pretty much all serial interfaces could report the actual number of bytes transported when writing to a serial port. So, what you would do is finish off your remainder of control bytes with 0x0 (binary 0) until you've accomplished the bytes you said you would send, and then re-submit your intended command, making sure you had transmitted enough bytes. Generally, this is safe.

I intend to add response data to the protocol in the not-so-distant future, so you can know whether your command was accepted or not.

So, yeah, as to pack templates - just remember that when it says it wants two bytes for a value, that you pick a template that produces an _unsigned big-endian value of exactly two bytes_ that would be 'n' in the perl pack templates. e.g., in perl I would say :

$data .= pack('n', $value);

A more complete example: (set motor 0 to 50 steps):

!c