Skip to content

API v.2 (outdated)

Jump to bottom
Andrey Voroshkov edited this page May 31, 2018 · 2 revisions

Device communication protocol

Each Chorus node Receives and Transmits data. Here's how the communication flow is organized from a node standpoint.

Basic concepts:

  1. Each node comprising the Chorus, has its ID (order number), which is assigned dynamically upon initialization of the Chorus device from a communicating application. Normally enumeration starts with 0 (using "N0\n" command).
  2. Each data chunk is a plain string terminated with "\n" character (ASCII=0xA) and having a predefined structure.
  3. There are 3 types of data chunks:
    • Requests
    • Responses
    • Pass-through data
  4. Almost each Request produces a Response
  5. Pass-through data is either a request to a different node, or a response which needs to pass through current node to reach the Bluetooth dongle and be transmitted to the application.

Requests

There are 2 types of requests:

  1. Nodes enumeration: (3 characters) "N" + <first_ID> + "\n". Example: "N0\n"
  2. Command/Request: (4+ characters) "R" + <node_ID> + <command> + "\n". Example: "R1T\n"
  3. Calibration request: "C" + <node_id> + <calibration_value> + "\n"

Any request may be addressed to any particular node by specifying its <node_ID>, or "broadcasted" (i.e. addressed to all nodes) by setting "*" as a <node_ID>. Example: "R*A\n"

Note: for broadcast requests the order of responses from different nodes is not defined. Example: "S1R1\nS0R1\nS2R1\n"

Responses

Response structure: "S" + <node_ID> + <response_type> + <data> + "\n" Each response type has its own predefined length depending on size of data to be transmitted.

Note:

  • All broadcast requests pass through all nodes and return to sender unchanged.
  • All addressed requests return to sender unchanged if target node is not found.
  • All addressed requests DON'T return to sender and are normally followed by a response (see API).

Correspondence of Requests to Responses (API)

The most recent version of API v2 is available among 0.7.5 release binaries: download (MS Excel format).

High-level communication process

NOTE: In commands I use below I omit the trailing "/n" character for simplicity, but this character is mandatory in each command!

  1. Run "Enumerate Nodes" command ("N0") to enumerate modules (REQUIRED!). Read the response to find out the number of nodes in the device. Modules numbering will start from zero. (Hint: you may send "N1" to start numbering from 1 if it's more convenient to you).

  2. Set the "Minimal Lap Time", which must be less than the fastest possible lap time during the upcoming race. This will make sure that Chorus won't report false laps if accidentally catches VTX RSSI peak from a nearby drone before the latter crosses the finish line. Also you should plan the track to avoid situations when drones fly in close proximity to the Chorus before the end of a lap.

  3. Set Frequency into each node using either "Set Frequency" command or "Set Channel" + "Set Band" (2 commands). Note: it's the responsibility of the race control software to remember which node is monitoring which frequency to further match Chorus responses to pilots in each heat.

  4. Calibrate Arduino Timers (optional step, but increases accuracy of measured lap times during the race across nodes). The calibration process is as follows:

    1. Send "Start Calibration" command to all nodes: "R*I"
    2. Wait for some time (I use about 10 seconds). Let's note this time in milliseconds as "tc".
    3. Send "End Calibration" command to all nodes: "R*i". Chorus will respond with measured times from each node:  S1I00002710, S0I00002715 ... Let's note a time from any node as "tn"
    4. Perform the following calculation for each node: cc = tc/(tc - tn), if tc - tn = 0, then set cc = 0 Here "cc" would mean something like "what time measured by this arduino should be increased/decreased by 1ms". E.g. cc=1000 means that each second measured by arduino gives an error of -1 millisecond, so this millisecond should be added by arduino to compensate the error.
    5. Send calculated cc values to each corresponding node using "Set Calibration Value" command (note it must be a signed 32bit value).
    6. You're done. Alternatively you may perform all adjustments (steps 4 - 5) in the race control software.

  5. Set threshold for each pilot. You may use one of the following:

    • "Set Threshold Value" command - to set already known threshold value (e.g. if you stored one from previous setting attempt).
    • Set threshold values to zero using "Set Threshold Value" command: "R*S0000"; then use "Set/Clear Threshold" command to start the threshold setting algorithm in Chorus, which will eventually reply with threshold values for the specified node(s). Here you should carefully monitor if threshold values are returned for all pilots that take part in the procedure, otherwise some pilot(s) might be not tracked at all during the heat.

  6. Start race using one of 2 possible commands. Choose whatever is convenient to you:

    • Start race with relative lap times: "R*R", - once the race is started, lap times will be calculated based on a previous lap end: e.g. lap #1: 0:30.500, lap #2: 0:28.240, ...
    • Start race with absolute lap times: "R*P", - once the race is started, lap times will represent a time passed since the race start: e.g. lap #1: 0:30.500, lap #2: 0:58.740 (time of lap 1 + time of lap 2), ...

  7. Stop the race when it's over using "End Race" command: "R*r". (REQUIRED!).

  8. Repeat from step 5 or 6 for each subsequent heat.

Clone this wiki locally