Based on the discussion from the 3/5/13 dev call.
Sorry I missed it, but have some feedback based on the couple changes I've submitted via git pull request as I have been tinkering on both sides of the architecture. I like the abstraction where we set certain behaviors between the two. If the cockpit says "go forward" or "turn port", the Arduino can have the logic to know how to do that, because maybe this is a 4 motor ROV and the coordination of the motors to pull a right turn is different than a 3 motor. I see uploading updated Arduino code to tell it how to coordinate the "turn right" command. The Cockpit does not need to be changed. I don't see how you can do this just in the cockpit code because the Arduino has to know to use the 4th motor. Limiting the change to just one area seems like good isolation.
As far as sensors go. I worry about potting me end caps because I feel I need to thread wires to extend the I2C bus outside so that I can extend it in the future. I don't the the Audrino is a great platform for interpreting the I2C data, there is not enough memory to store much. I can see the Arduino passing the I2C data along to the beagle and to cockpit for interpretation. In this case I can imagine dropping in a controller for that sensor in to the cockpit software that explains how to interpet and work with the sensor data. These can be uploaded to the cockpit software.
You don't have to use the Arduino IDE to program the Arduino. It compiles on the beagle. All you do is chance the C files and run the ino build on the beagle. You could expose these files in a text editor through the cockpit, the beagle can compile and load it on the Arduino for you. You should be able to drop in a new servo.c file that is more gental in power management of the servos.
I do think that github is right place to store the software design concepts. It has a baked in wiki solution for this and it is tied to the version numbers and follows the distributed changes. Someone might have an spin on the cockpit software that we want to merge in to the standard version, it is nice is the documentation changes come with it. Usually these projects have all you need in one place to understand the conventions of the team developing the software.