From a7fbfb46cab5aa0c5684f319af80a0d46357bbf4 Mon Sep 17 00:00:00 2001 From: Michael DM Dryden <mdryden@chem.utoronto.ca> Date: Tue, 11 Jul 2017 19:42:28 -0400 Subject: [PATCH] Update communications protocol documentation. --- communication protocol.txt | 259 +++++++++++++++++++++++++++---------- 1 file changed, 194 insertions(+), 65 deletions(-) diff --git a/communication protocol.txt b/communication protocol.txt index 8ae7409..6905ca4 100644 --- a/communication protocol.txt +++ b/communication protocol.txt @@ -1,70 +1,199 @@ DStat communications protocol -Initialization (can be done again even after initialized, if needed): - Send 'C' - Reply '#' - Send 'k' +Lines replied starting with '#' are human-readable info messages that should be logged +Lines replied starting with '@' are status codes from the DStat +The DStat can be restarted by simply disconnecting from the virtual serial port. + Disconnecting and reconnecting will return the DStat to the root command menu. Command protocol: - Send '!' - Other characters sent first will be rejected with reply 'C\n' - Send command and arguments (see below) - Lines replied starting with '#' are human-readable info messages that should be logged - All commands terminate by replying "no\n" - -Commands - single letter command with arguments in C scanf format : - ADC setting - Send 'A' - Send "%hhx%hhx%hhx" - ADS Buffer/Rate/PGA value - - Gain setting - Send 'G' - Send "%u" - gain value - - Linear Sweep Voltammetry - Send 'L' - Send "%u%u%i%i%i%i%u" - t_preconditioning1, t_preconditioning2, v_preconditioning1, - v_preconditioning2, start, stop, slope - Replies continuously with data after preconditioning time: - Each point: - "B\n" followed by uint16 voltage and int32 current, then "\n" - - Cyclic Voltammetry - Send 'C' - Send "%u%u%i%i%i%i%i%hhu%u" - t_preconditioning1, t_preconditioning2, - v_preconditioning1, v_preconditioning2, v1, v2, start, - number of scans, slope - Replies continuously with data after preconditioning time: - Each point: - "B\n" followed by uint16 voltage and int32 current, then "\n" - End of each scan: - "S\n" - End of experiment: - "D\n" - - Square Wave Voltammetry - Send 'S' - Send "%u%u%i%i%i%i%u%u%u%u" - t_preconditioning1, t_preconditioning2, - v_preconditioning1, v_preconditioning2, start, stop, - step size, pulse_height, frequency, scans - Replies continuously with data after preconditioning time: - Each point: - "B\n" followed by uint16 voltage, int32 forward_current, - int32 reverse_current, then "\n" - End of each scan: - "S\n" - End of experiment: - "D\n" + Send '!' - Other characters sent first will not produce a response + Send number of characters in command to follow (0–65535) + DStat will reply '@ACK %u\n' where %u is the number of characters requested. + If 0, DStat will reply '@RCV 0 \n' immediately (Can use to check if DStat is communicating properly) + Send command and arguments (see below), terminated by '\n' (use spaces not \n to separate arguments) + DStat will reply '@RCV %u\n' where %u is the number of characters read and then '#%s\n' where %s is the command string received + If there is a problem reading the string, the DStat will reply '@ERR' instead followed by a message + + Some commands require additional parameters: + If so, DStat will send '@RQP %u\n' where %u is the number of parameters expected. + Send the parameters one at a time. + DStat will reply `@RCVC %\n' where % is the parameter just sent. + If there's an error, DStat will reply `@RCVE\n', and will wait for the last parameter to be resent. + When all parameters have been sent, DStat will reply '@RCP %u\n' where %u is the number of parameters received. + All commands terminate by replying '@DONE\n' + +Main Command menu - single letter commands : + Restart USB Stack: + *Will disconnect USB device from computer and need to be reenumerated* + Send 'R' + Check Version: + Send 'V' + DStat will return a string containing the PCB version and firmware git revision: + "V%u.%u.%u-%lu\n", BOARD_VER_MAJOR, BOARD_VER_MINOR, BOARD_VER_MICRO, GIT_COMMIT + *GIT_COMMIT is in decimal, not hex* + Perform Experiment: + Send 'E' + Send one of the commands below: + Experiments can be aborted while running by sending 'a' + Results are returned in ADC/DAC units: + For voltages (potentiometry experiments): Volts = adc_code/(adc_PGA_gain/2)*(1.5/8388607.) + For currents: Amps = (adc_code/(adc_PGA_gain/2))*(1.5/iv_gain/8388607) + adc_PGA_gain: the PGA gain setting of the ADC. Normal setting is 2x (±1.5 V full-scale) + iv_gain: the gain of the transimpedance amplifier in ohms + + For voltages (voltammetry): Volts = (dac_code-32768)*3./65536 + + ADC setting + Send 'A' + Send "%hhx%hhx%hhx" - ADS Buffer/Rate/PGA value + + Gain setting + Send 'G' + Send "%u" - gain value + + #define POT_GAIN_0 0 + #define POT_GAIN_100 1 + #define POT_GAIN_3k 2 + #define POT_GAIN_30k 3 + #define POT_GAIN_300k 4 + #define POT_GAIN_3M 5 + #define POT_GAIN_30M 6 + #define POT_GAIN_100M 7 + + Chronoamperometry + Send 'R' + Send '%hhu%hhu' - number of potential steps, 0 (Sets up light sensor for custom box if > 0) + + DStat will request voltage and time steps: '@RQP %u\n' where %u is 2 * number of steps + Send a list of voltage steps according to additional parameter protocol above. + Send a list of time steps according to additional parameter protocol above. + DStat will reply '@RCP %u\n' when done where %u is 2 * number of steps. + + Replies continuously with data: + Each point: + "B\n" followed by (in binary, not text) uint16 seconds, uint16 milliseconds, int32 current, then "\n" + End of experiment: + "D\n" + + Linear Sweep Voltammetry + Send 'L' + Send "%u%u%i%i%i%i%u" - t_preconditioning1, t_preconditioning2, v_preconditioning1, + v_preconditioning2, start, stop, slope + Replies continuously with data after preconditioning time: + Each point: + "B\n" followed by uint16 voltage and int32 current, then "\n" + + Cyclic Voltammetry + Send 'C' + Send "%u%u%i%i%i%i%i%hhu%u" - t_preconditioning1, t_preconditioning2, + v_preconditioning1, v_preconditioning2, v1, v2, start, + number of scans, slope + Replies continuously with data after preconditioning time: + Each point: + "B\n" followed by uint16 voltage and int32 current, then "\n" + End of each scan: + "S\n" + End of experiment: + "D\n" + + Square Wave Voltammetry + Send 'S' + Send "%u%u%i%i%i%i%u%u%u%u" - t_preconditioning1, t_preconditioning2, + v_preconditioning1, v_preconditioning2, start, stop, + step size, pulse_height, frequency, scans + Replies continuously with data after preconditioning time: + Each point: + "B\n" followed by uint16 voltage, int32 forward_current, + int32 reverse_current, then "\n" + End of each scan: + "S\n" + End of experiment: + "D\n" - Differential Pulse Voltammetry - Send 'S' - Send "%u%u%i%i%i%i%u%u%u%u" - t_preconditioning1, t_preconditioning2, - v_preconditioning1, v_preconditioning2, start, stop, - step size, pulse_height, period, width - Replies continuously with data after preconditioning time: - Each point: - "B\n" followed by uint16 voltage, int32 forward_current, - int32 reverse_current, then "\n" - End of each scan: - "S\n" - End of experiment: - "D\n" + Differential Pulse Voltammetry + Send 'S' + Send "%u%u%i%i%i%i%u%u%u%u" - t_preconditioning1, t_preconditioning2, + v_preconditioning1, v_preconditioning2, start, stop, + step size, pulse_height, period, width + Replies continuously with data after preconditioning time: + Each point: + "B\n" followed by uint16 voltage, int32 forward_current, + int32 reverse_current, then "\n" + End of each scan: + "S\n" + End of experiment: + "D\n" + + Potentiometry: + Send 'P' + Send '%u%hhu' + Measurement time in s (if 0, can only be stopped with abort signal) + Mode: 0 for OCP (WE is connected)/1 for potentiometry (WE input disconnected) + + Replies continuously with data after preconditioning time: + Each point: + "B\n" followed by (in binary, not text) uint16 seconds, uint16 milliseconds, int32 voltage, then "\n" + End of experiment: + "D\n" + + Settings: + Send 'S' + Send one of the commands below: + + Restore settings to defaults: + Send 'D' + + Enter firmware update mode (DFU): + Send 'F' + + Read settings from EEPROM: + If no settings are present, defaults will be loaded. + + Send 'R' + DStat will print settings first in human readable form prefixed by '#' + DStat will print a single string containing settings: + e.g. "Smax5443_offset.%u:tcs_enabled.%u:tcs_clear_threshold.%u:r100_trim.%i:r3k_trim.%i:r30k_trim.%i:r300k_trim.%i:r3M_trim.%i:r30M_trim.%i:r100M_trim.%i\n" + - Starts with 'S' + - A series of key/value pairs where the key is a string, the key and value are separated with '.' and different pairs are separated with ':' + - Ends with '\n' + + *Be sure to preserve the order of key/value pairs as they must be entered in the correct order when writing new settings* + + Write settings to EEPROM: + Send 'W' + Send a list of the new settings values separated and terminated by a space, *in the same order as read with the R command* + + +Example of a SWV experiment: + Set ADC settings (Info strings not shown): + Computer !9\n Request to send 9 byte command + DStat @ACK 9\n Clear to send command + C EA2 A1 1 \n PGA 2x, sample rate 1 kHz, Input buffer on + D @RCV 9\n Received 9 byte command + D @DONE\n Command completed + Set Gain: + C !6\n Request to send 6 byte command + D @ACK 6\n Clear to send command + C EG2 0 \n Set gain to 3 kΩ + D @RCV 6\n Received 6 byte command + D @DONE\n Command completed + Start SWV experiment: + C !41\n Request to send 41 byte command + D @ACK 41\n Clear to send command + C ES10 10 50244 10922 -1000 -300 3 20 30 0 \n 10 s clean @ 800 mV, 10 s deposition @ -1000 mV, + Start -1000 mV, Stop -300 mV, Step size 3 mV, + Pulse Height 20 mV, Frequency 30 Hz, No cyclic mode (scans=0) + D @RCV 41\n Received 6 byte command + Data output: + D B\n A datapoint follows (length depends on experiment type) + D *10 bytes of binary data* uint16 voltage, int32 forward current, int32 reverse current + D \n + . + . + . + D D\n Data output finished + D @DONE\n Command completed + + + + \ No newline at end of file -- GitLab