initial radio protocol brainstorm

firmware/common2015/modules/CommProtocol/.gitignore

@@ -0,0 +1 @@
+protocol.capnp.*

firmware/common2015/modules/CommProtocol/example.txt

@@ -0,0 +1,14 @@
+
+(
+    from = 0,
+    datagrams = [
+        (
+            port = motionCommands,
+            data = "0x56000000000000"
+        ),
+        (
+            port = motionCommands,
+            data = "0x234123421000000000000000000000000000000000000000"
+        )
+    ]
+)

firmware/common2015/modules/CommProtocol/makefile

@@ -0,0 +1,17 @@
+
+protocol.capnp.c++: protocol.capnp
+	capnp compile -oc++ protocol.capnp
+
+
+.PHONY: encode
+
+encode: example.txt protocol.capnp
+	@echo "Number of bytes without packing:"
+	@cat example.txt \
+	| capnp encode protocol.capnp RadioPacket \
+	| wc -c
+
+	@echo "Number of bytes with packing:"
+	@cat example.txt \
+	| capnp encode -p protocol.capnp RadioPacket \
+	| wc -c

firmware/common2015/modules/CommProtocol/protocol.capnp

@@ -0,0 +1,130 @@
+@0xd0e5f899630c4695; # unique file ID, generated by `capnp id`
+
+# 2015 Robot Radio Protocol
+
+
+# If a certain participant misses X slots in a row, it is dropped from the group
+# The host sends a list of addresses that can talk after the host message finishes.
+# Each participant replies in turn.  The next person in the convo waits X amount
+# of time listening before assuming that the other one has given up before
+# continuing to the next in turn.
+# A robot's reply can be variable-length, but it must start its transmission
+# within X amount of the previous talker or else it's slot is dropped.
+#
+# Questions
+# - how to ensure unique addresses?
+# - Are talk slots efficient in competition mode?
+# - How to make reliable transfer easy?
+# - encoded size of Float32 vs Int16?
+
+# CommModule::send() places a datagram on the queue to be sent.
+# * Caveats: If an item is placed that has the same port number on an unreliable
+#            protocol, it replaces the existing packet in the queue.
+# * At send time, datagrams are popped off the queue up to a set size, then
+#   placed into a packet and sent.
+# * A packet should be ready to go before the reply slot comes
+
+
+################################################################################
+
+struct Vector2F {
+    x @0 :Float32;
+    y @1 :Float32;
+}
+
+
+struct MotionCommandDatagram {
+    struct MotionCommand {
+        vel @0 :Vector2F;
+        angVel @1 :Float32;
+
+        # kick/chip power
+        kickPower @2 :Float32;
+
+        # true == chip, false == kick
+        chip @3 :Bool = false;
+
+        # If true, the kick happens as soon as the packet is received.  If false,
+        # The kick happens as soon as the ball sensor is tripped.
+        kickImmediately @4 :Bool = false;
+
+        dribblePower @5 :Float32;
+    }
+
+    # A command in the same order and quantity as the robots specified in the
+    # main RadioPacket's @replySlots field
+    commands @0 :List(MotionCommand);
+}
+
+################################################################################
+
+# Robot sends this back to the base station
+struct RobotStatusUpdateDatagram {
+    enum MotorStatus {
+        good @0;
+        hallFault @1;
+        encoderFault @2;
+        stall @3;
+    }
+
+    batteryVoltage @0 :Float32;
+    kickerVoltage @1 :Float32;
+    errorBitmask @2 :UInt32;
+    ballSensor @3 :Bool;
+
+    # array with 5 entries: [FR, FL, BL, BR, Dribbler]
+    motorStatuses @4 :List(MotorStatus);
+
+    # TODO: kicker status?
+}
+
+
+################################################################################
+
+struct RadioPacket {
+
+    struct Datagram {
+        # All ports used with radio communication are listed here.
+        enum Port {
+            # During regular use, the base station sends a motionCommands
+            # datagram containing commands for each robot, then each robot in
+            # turn replies with a robotStatusUpdate datagram.
+            motionCommands @0;
+            robotStatusUpdate @1;
+
+            # Used for updating parameter values on a robot.
+            paramaterSync @2;
+
+            # Used to upload a new robot firmware binary.
+            fileTransfer @3;
+
+            # Interface with robot terminal wirelessly
+            shell @4;
+        }
+
+        port @0 :Port;
+
+        # The data itself. This is typically an encoded protobuf, but differs
+        # from port to port.
+        data @1 :Data;
+    }
+
+    # Addresses of sender and receiver
+    from @0 :UInt16;
+    to @1 :UInt16;
+
+    # Packet data contents
+    datagrams @2 :List(Datagram);
+
+    # An ordered list of addresses of robots that are allowed to reply after
+    # this message. This field is only set in a packet from the host.
+    commSlots @3 :List(UInt16);
+}
+
+
+# Datagram type used for two-way reliable transfer
+struct ReliableTransferPacket {
+    sequence @0 :UInt16;
+    data @1 :Data;
+    ack @2 :UInt16;
+}

firmware/common2015/modules/CommProtocol/readme.md

@@ -0,0 +1,6 @@
+
+# CommProtocol
+
+This is a brainstorm for the new radio protocol.
+
+