Telegram Exchange

The FreiStat software on the microcontroller communicates by using JSON-telegrams. The exchange of telegrams is thereby bidirectional and can be separated into the following types of telegrams:

Defined "Telegram Identifier" :

• "C" : Command Telegram
• "A" : Acknowledge Telegram
• "R" : Data Telegram

Command telegrams

Command telegrams are used to configurate the FreiStat software on the microcontroller by an external software. Depending on the chosen "Command Type" the telegram is interpreted differently by the microcontroller.

Defined "Command Type" :

• "ExT" : Experiment type
• "ExP" : Experiment parameters
• "ExC" : Control Command
• "ExS" : Experiment sequence

The sequence of transmitted telegrams follows a defined order. In a first step, the experiment type transmitted. This telegram is acknowledged by the microcontroller. The microcontroller expects then a telegram containing the matching experiment parameters for the chosen electrochemical method. This telegram is acknowledged again by the microcontroller. After this a last telegram with a start command is required. This is also acknowledged by the microcontroller, which then starts executing the experiment.

To stop the experiment a telegram containing a stop command must be send to the microcontroller. The controller acknowledges this telegram and sends back a control command containing a stop command.

---

1 Experiment Type

The first telegram which must to be send contains the experiment type. In the current version, the FreiStat supports 6 different electrochemical methods, which are listed below. Each of these methods use a unique set of experiment parameters, which is explained on their respective wiki page.

Defined "Experiment Type" :

• "CA" : Chronoamperometry
• "LSV" : Linear Sweep Voltammetry
• "CV" : Cyclic Voltammetry
• "NPV" : Normal Pulse Voltammetry
• "DPV" : Differential Pulse Voltammetry
• "SWV" : Square Wave Voltammetry

Structure:

The base structure of the experiment type telegram is depicted below.

{"Telegram Identifier": 1,"Command Type": "Experiment Type"}

• Telegram Identifier is always "C" for telegrams containing the experiment type
• Command Type is always "ExT", which abbreviates Experiment Type
• Experiment Type indicates the microcontroller which experiment should be executed

Example:

The following JSON-telegram shows the example for cyclic voltammetry.

{"C":1,"ExT": "CV"}

---

2 Experiment Parameters

After the telegram with the experiment type was send, the required experiment parameters for the chosen method must be transmitted. As explained above, each method requires different parameters, which are explained on the wiki page of the respective method.

Thereby not all experiment parameters need to be send. If parameters are omitted, the internally defined default values are used. Furthermore, the order of experiment parameters can be chosen arbitrarily.

Structure:

The base structure of the experiment parameter telegram is depicted below.

{"Telegram Identifier": 2,"Command Type": {"Parameter 1":"Value", "Parameter 2":"Value"}}

• Telegram Identifier is always "C" for telegrams containing the experiment parameters
• Command Type is always "ExP", which abbreviates Experiment Parameters
• {...} contains all the experiment parameters stored as indexed values

Example:

The following JSON-telegram shows the example for cyclic voltammetry.

{"C":2,"ExP":{"pSP":500.4395,"pLP":-620.0,"pUP":1050.0,"pSZ":2.0,"pSR":200.0,"pC":1,"pLRS":11,"pFWP":1,"pMF":0,"pOS2":1,"pOS3":2}}

---

3 Control Commands

The last telegram required to start an experiment is a control command with the "start" keyword. This telegram can be send at an arbitrary time after the first two telegrams have been send. Same applies for the telegram, which contains the "stop" keyword, that terminates the running experiment.

Defined "Operating Commands" :

• "Start" : Start experiment
• "Stop" : Stop experiment

Structure:

The following JSON-telegram shows the example for an start telegram.

{"Telegram Identifier": 3,"Command Type": "Operating Command"}

• Telegram Identifier is always "C" for telegrams containing control commands
• Command Type is always "ExC", which abbreviates Experiment Control
• Operating Command contains one of the defined keywords

Example:

{"C":3,"ExC": "Start"}

---

4 Enable or Disable Sequence Mode

In contrast to the previously explained sequence of telegrams to start 1 electrochemical method, the sequence mode can be used to execute a list of electrochemical methods. The working principle behind this is as follows. The telegram, which enables the sequence mode is send to the microcontroller. This is then followed up by an telegram containing the experiment parameters for the sequence. Then packages of experiment type and experiment parameter telegrams are send to the controller for every method, which should be executed. After this, the telegram to disable the sequence mode is send. Lastly, the normal start telegram gets transmitted to start the sequence.

Defined "Operating Commands" :

• "SE" : Sequence mode enabled
• "SD" : Sequence mode disabled

Structure:

{"Telegram Identifier": 4,"Command Type": "Operating Commands"}

• Telegram Identifier is always "C" for telegrams containing sequence mode control commands
• Command Type is always "ExC", which abbreviates Experiment Sequence
• Operating Command contains one of the defined keywords

Example:

The following JSON-telegram shows the example for starting the sequence mode on the microcontroller.

{"C":4,"ExS": "SE"}

Acknowledge telegrams

Acknowledge telegrams are the response of the microcontroller to received telegrams. The telegrams are thereby very short and only contain a number, which is equivalent to the previously received "Telegram Identifier" value.

Defined "Value" :

• 1 : Experiment Type
• 2 : Experiment Parameters
• 3 : Control command
• 4 : Control sequence mode

Structure:

{"Telegram Identifier": "Value"}

• Telegram Identifier is always "A" for telegrams acknowledge telegrams
• Value is equivalent to the previously received "Telegram Identifier" value.

Example:

The following JSON-telegram shows the example for acknowledging a "Experiment Type" telegram.

{"A":1}

Data telegrams

Data telegrams are send from the microcontroller to the python framework in certain time intervals. These depend on the chosen electrochemical method and the experiment parameters. Regardless of the method, the data telegram is always structured in the same way.

Defined "Keywords" :

• "R" : Cycle
• "M" : Measurement values
• "D" : Datapoint to identify measurement
• "V" : Measured voltage value (in mV)
• "C" : Measured current value (in μA)
• "T" : Time stamp since microcontroller was started (in ms)

Structure:

{"R": "Cycle number","M":{"D":"Datapoint","V":"Voltage value","C":"Current value","T":"Time stamp"}}

Example:

The following JSON-telegram shows the example for measurement point 180 during the first cycle.

{"R":1,"M":{"D":180,"V":889.40173,"C":8.88046,"T":14451}}