JSON serial format
The serial interface supports a JSON string format. To use the JSON format the device that is being interfaced must have built in support for the format. It is up to you the developer to implement the support for the JSON serial format in your device and test equipment. Below you will find the specifications for the JSON serial format for you to implement and instructions on how to use the JSON commands in the Config Manager.
JSON format specification
Command sent to the device
The format of the commands the device/equipment receive are standardized to allow the system to add arguments to commands such as the set ID command. The only requirement for the device commands json string is that it contains the key “command”, associated with string that represents the command sent to the device. Additional keys can be used as arguments to the commands. For generated commands such as set ID there are standard argument names that the commands should support So that the system can add the generated data to the argument of the command. See Standard arguments for further information on the standard arguments.
Unlike the shell format the json format is not terminated with a new line char. When format is set to json the system looks for the ‘}’ char as the termination of a message. This means that the json strings sent from the DUT can be formatted for readability. This applies to the messages sent from the system as well. Commands are sent in a compact format, not containing any tabs, spaces, or new lines. The DUT should use the ‘}’ char to terminate the incoming message.
1{
2 "command": "get_device_current",
3 "user defined param 1": "what ever the device needs",
4 "user defined param 2": 30,
5 "...": "..."
6}
Response from device
Every message/command sent to the device must respond with a message containing at least the ‘status’ and ‘ack’ key-value pairs. Where status indicates the status of the command execution where “ok” means successful command execution and the ack should be the sent command repeated to confirm what command was executed. That is the value of the command key in the json string received by the DUT. Commands that return a value to the test runner should additionally contain the ‘result’ key-value pair. The result key should only contain integer values. This would be a response to the commands that are executed under the test entry at each test stage.
You can add as many keys to the response as you like, but only the keys listed above will be used by the system. Below is an example response from a device. This example contains the results from a test and an optional “debug”key. The debug message is only saved to a test report when the device responds with status: “error”.
1{
2 "status": "ok",
3 "ack": "get_device_current",
4 "result": 50,
5 "debug": "Expected x but got y, is the cable connected?"
6}
Standard arguments
Standard arguments are arguments that the system adds to commands. These arguments are generated by the system such as IDs. Below are standard arguments to commands that your device needs to support to utilize certain features of the system.
Set identification
Under the set entry under the identification stage, you can define the command the device uses to assign it an ID. In the json editor in the config manager you Only need to specify the command key. The system will add the generated ID as an argument to the json string sent to the device. The argument added uses the key “id”.
For example, the set command in the json editor can look something like:
1{
2 "command": "set_id"
3}
The json string sent to the device with the added generated argument would look like:
1{
2 "command": "set_id",
3 "id": 10000234,
4}
This example would assign the device the id 10000234.
Using JSON in the test config
In the config manager under the stage equipment config for the DUT you need to set the format parameter to ‘json’. This will allow you to use the DUT JSON Command editor tab in the config editor to define the json string commands that you can reference in the test config. The below config shows the format set to json.
1equipment:
2 dut:
3 baud-rate: 9600
4 com-type: 'serial'
5 format: 'json'
6 usbVendorId: 6790
Once you set the format of the dut to json you will be able to use the json editor. Select the DUT JSON Commands tab above the text editor to open the json command editor.
Now lets add a json command. In the editor, add the command you wish to send to the device like shown below.
1{
2 "reference_name1":{
3 "command": "MyFirstCommand",
4 "argName": "OptionalArgument"
5 },
6 "reference_name2":{
7 "command": "MySecondCommand"
8 }
9}
Not that you have defined your json commands you can use them in a test config by referencing the name of each json object. In the example above, we would reference to “reference_name1” and “reference_name2” to use the corresponding json object. Let’s now use the json commands we created. In the test config tab, we will add the command strings.
1- "dut :$ reference_name1"
2- "dut :$ reference_name2"
The above command strings will send the json objects associated with the reference as a string over serial to the dut.
The example Arduino sketch in the quick start guide supports “get_id”, “set_id” and “test” commands in json format. Let’s create a test config that runs identification and a single test with the json format. The config should be as follows.
the json commands:
1{
2 "test_command":{
3 "command": "test"
4 }
5 "set_id_command": {
6 "command": "set_id"
7 }
8 "get_id_command":{
9 "command": "get_id"
10 }
11}
The yaml test config:
1equipment:
2 dut:
3 baud-rate: 9600
4 com-type: 'serial'
5 format: 'json'
6 usbVendorId: 6790
7
8identification:
9 dut:
10 get:
11 -"dut:$ get_id_command"
12 set:
13 -"dut :$ set_id_command"
14
15test_accelerometer:
16 description:
17 - "Test the accelerometer"
18 criteria:
19 max: 15
20 min: 5
21 test:
22 - "dut:$test_command"
Connect an Arduino with the example sketch found under the quick start guide and run the test in the config manager. The device should successfully identify and pass the accelerometer test.