|
|
|
|
|
# FlockLab XML Test Configuration File Help
|
|
|
|
|
|
The FlockLab XML test configuration file defines everything needed for a single FlockLab test: when a test should start and stop, which platform and operating system are used, which services are used and how the test results are going to be retrieved.
|
|
|
* The XML is validated against an [XML schema definition](https://www.flocklab.ethz.ch/user/xml/flocklab.xsd).
|
|
|
* We provide a [sample configuration file](https://www.flocklab.ethz.ch/user/xml/flocklab_template.xml) (including an image for the `dpp` (CC430 sensor node))
|
|
|
* Test configuration files can be [validated](https://flocklab.ethz.ch/user/xmlvalidate.php) (without being actually registered in FlockLab).
|
|
|
|
|
|
<br />
|
|
|
|
|
|
:point_right: If you have an old XML config of FlockLab 1, you can adjust the config according to this [porting guide](/Man/XmlPortingGuide).
|
|
|
|
|
|
<br />
|
|
|
|
|
|
|
|
|
### Structure of the test configuration
|
|
|
|
|
|
A test configuration consists of several blocks:
|
|
|
* A block with the general configuration of the test: when a test starts/ends, which targets are used and so on.
|
|
|
* Blocks with the configurations for all targets: which image is used, which ID an image should have and the used voltage
|
|
|
* Blocks for each service used in the test. These blocks are only needed for services which are actually needed.
|
|
|
All configuration elements have to be embedded into the outermost elements:
|
|
|
|
|
|
```
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
<testConf xmlns="http://www.flocklab.ethz.ch" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.flocklab.ethz.ch xml/flocklab.xsd">
|
|
|
...
|
|
|
</testConf>
|
|
|
```
|
|
|
|
|
|
Next, place the needed configuration elements into this structure:
|
|
|
|
|
|
1. [`<generalConf>`](/Man/XmlConfig#general-configuration): 1 element has to be specified.
|
|
|
1. [`<targetConf>`](/Man/XmlConfig#target-configuration): 1 or more elements have to be specified.
|
|
|
1. [`<serialConf>`](/Man/XmlConfig#serial-service-configuration): 0 or more elements can be specified. Do only specify if needed.
|
|
|
1. [`<gpioTracingConf>`](/Man/XmlConfig#gpio-tracing-service-configuration): 0 or more elements can be specified. Do only specify if needed.
|
|
|
1. [`<gpioActuationConf>`](/Man/XmlConfig#gpio-actuation-service-configuration): 0 or more elements can be specified. Do only specify if needed.
|
|
|
1. [`<powerProfilingConf>`](/Man/XmlConfig#power-profiling-service-configuration): 0 or more elements can be specified. Do only specify if needed.
|
|
|
1. [`<embeddedImageConf>`](/Man/XmlConfig#embedded-image-configuration): 0 or more elements can be specified. Do only specify if needed.
|
|
|
1. [`<debugConf>`](/Man/XmlConfig#debug-configuration): 0 or more elements can be specified. Do only specify if needed.
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### General Configuration
|
|
|
|
|
|
The element `<generalConf>` defines the general test configuration.
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|----------------------|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
|
|
|
| `name`* | A short, meaningful name for the test. | 5 - 45 characters |
|
|
|
| `description` | More comprehensive description of the test. | max. 512 characters |
|
|
|
| `custom` | A custom tag, can contain arbitrary user defined data. Note: tags `<...>` are not allowed within this element. | max. 4096 characters |
|
|
|
| `schedule`* | Defines the test start time and duration. | |
|
|
|
| `emailResults` | If set, the test results are emailed to the user by the end of the test. The email address is taken from the user account settings. | possible values: `yes`, `no`. Default: `no` |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
##### `<schedule>`
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|-----------|-----------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
|
|
|
| `start` | Start time in UTC of the test. Check the [schedule](https://user.flocklab.ethz.ch/calendar.php) for free slots. If no start time is provided, the test will run as soon as possible. | `YYYY-mm-ddTHH:MM:SSZ`, e.g. 2011-08-20T16:00:00Z |
|
|
|
| `duration`* | Duration of the test in seconds. | min. is 20 seconds, max. is limited by the users quota |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### Target Configuration
|
|
|
|
|
|
All targets used in a test need to be defined within the `<targetConf>` element.
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
|
| `obsIds`* | One or more ID of the observer(s) to be configured. If you want to use all available observers, you can specify `ALL` instead of listing all observer IDs. <br> [-> How to use obsId in the code](Man/HowTo#how-to-assign-node-ids) | Observer ID(s) separated by spaces. Consult the [nodelist](https://flocklab.ethz.ch/user/nodelist.php) page for a list of usable observers and targets attached to the observers. |
|
|
|
| `targetIds` | Optional user-defined ID(s) for the target(s). The node ID(s) of the target(s) will be set to these values. For each observer ID in `<obsIds>`, a corresponding target ID is required in `<targetIds>`. <br> [-> How to use targetId in the code](Man/HowTo#how-to-assign-node-ids) | 16bit unsigned integer(s) separated by spaces. |
|
|
|
| `voltage` | Voltage in volt with which the target is to be powered. | 1.8 - 3.3 in 0.1 steps. If element is not specified, 3.3 is assumed. |
|
|
|
| `dbImageId`* | Image ID from the FlockLab database to be used on this target(s). Consult the [images management](https://www.flocklab.ethz.ch/user/images.php) site for a list of available images. Note that an image has to be uploaded to the images management site before it can be referenced here. Either `<dbImageId>` or `<embeddedImageId>` has to be specified. | |
|
|
|
| `embeddedImageId`* | Image ID referencing an `<embeddedImageConf>` element in the XML configuration containing an image binary. Either `<dbImageId>` or `<embeddedImageId>` has to be specified. | Any combination of characters, numbers and underline |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### Embedded Image Configuration
|
|
|
|
|
|
`<embeddedImageConf>`. Target images can be defined in two ways for a test: either by referencing an image which is already in the FlockLab database or by adding the image directly to the XML configuration file. The latter case is done with `<embeddedImageConf>` elements.
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
|
|
|
| `embeddedImageId`* | Image ID referenced by `<targetConf>` element. | any combination of characters, numbers and underline |
|
|
|
| `name`* | A short, meaningful name for the image. | 5 - 45 characters |
|
|
|
| `description` | More comprehensive description of the image. | max. 512 characters |
|
|
|
| `platform`* | Target platform for which the image is intended. | Possible values: `tmote`, `dpp`, `dpp2lora`, `nrf5` |
|
|
|
| `core` | Specify the core/MCU, only of interest for platforms with more than one MCU. | for the DPP: 0 = CC430, 1 = BOLT, 2 = MSP432 |
|
|
|
| `data`* | The image itself. You can use [this script](https://gitlab.ethz.ch/tec/public/flocklab/flocklab/blob/master/tools/scripts/embed_image.sh) to embed an image into the XML file. | base64 encoded string of exe/elf or Intel hex file |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### Serial Service Configuration
|
|
|
|
|
|
To use the serial service, define a `<serialConf>` block with the following configuration elements:
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
|
|
|
| `obsIds`* | One or more observer IDs for which this service should be used. Note that all IDs used here have to have a target configuration as well. | ID(s) of the observer(s) to use |
|
|
|
| `port` | Which port to use for serial communication. <br />_Note 1_: In order for port `swo` to work, the SWD debug pins (SWDIO, SWDCLK) must not be reconfigured as output pins. <br />_Note 2_: for port `serial` the `baudrate` element is requried, for port `swo` the `cpuSpeed` element is required! | Possible values: `usb`, `serial`, `swo`. Default is `serial` |
|
|
|
| `baudrate` | Baud rate to use when reading. Note that the highest baudrates may not work properly when the serial proxy is not used (see below). Also, bit errors are more likely with higher baudrates. | Possible values: 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000. Default is 115200 |
|
|
|
| `cpuSpeed` | Defines the target CPU speed (required if port `swo` is selected). | frequency in Hertz |
|
|
|
| `remoteIp` | IP address from which serial data will be sent to node. If not specified, the serial proxy service will not be used. If left blank, the IP of the machine that registered the test will be used. <br >Notes: <br />- If your machine only has an IPv6 address, then the XML validation will fail.<br />- Timestamping will be more accurate if the proxy service is not used (no `<remoteIp>` element in the XML config). | IPv4 address |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
[How to connect to the serial service.](https://gitlab.ethz.ch/tec/public/flocklab/flocklab/-/wikis/Services#serial-service-logging-forwarding)
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### GPIO Tracing Service Configuration
|
|
|
|
|
|
To use the GPIO tracing service, define a `<gpioTracingConf>` block with the following configuration elements:
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
|
|
|
| `obsIds`* | One or more observer IDs for which this service should be used. Note that all IDs used here have to have a target configuration as well. | ID(s) of the observer(s) to use |
|
|
|
| `pins`* | Defines which pin to trace. See [GPIO list](/Man/GpioAssignmentTargetAdapter) for pin assignments. Important: make sure the pins you want to trace are never in a floating / undefined state! | possible values: `INT1`, `INT2`, `LED1`, `LED2`, `LED3` |
|
|
|
| `offset` | Postpone the sampling start. Offset relative to the start of the test, in seconds. Default value is 1. | unsigned integer |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### GPIO Actuation Service Configuration
|
|
|
|
|
|
Remark: the default level of both actuation pins (`SIG1`, `SIG2`) is low. If the actuation service is not used, the actuation pins will remain in low state during the whole test. In addition to the `SIGx` pins, the target reset (`nRST`) can also be actuated.
|
|
|
|
|
|
To use the GPIO actuation service, define a `<gpioActuationConf>` block with the following configuration elements:
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|-------------|------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|
|
|
|
| `obsIds`* | One or more observer IDs for which this service should be used. Note that all IDs used here have to have a target configuration as well. | ID(s) of the observer(s) to use |
|
|
|
| `pinConf`* | One or more blocks containing configuration for one pin. | (see below) |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
##### `<pinConf>`
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|
|
|
|
| `pin`* | Subelement of `<pinConf>`. Defines which pin to set/clear/toggle (event). See [GPIO list](../Man/GpioAssignmentTargetAdapter) for pin assignments. | possible values: `SIG1`, `SIG2`, `nRST` |
|
|
|
| `level`* | Subelement of `<pinConf>`. Defines to which level the pin is to be actuated. | possible values: `low`, `high`, `toggle` |
|
|
|
| `offset`* | Subelement of `<pinConf>`. Defines an event relative to the start time of the whole test (offset in seconds). | float value between 0.0 and 4000.0 |
|
|
|
| `period` | Subelement of `<pinConf>`. If set, the event will be periodic with the chosen period (in seconds). Within one period, the pin will be toggled twice. | float value between 0.001 and 1000.0 |
|
|
|
| `count` | Subelement of `<pinConf>`. Defines the number of cycles for periodic events. One cycle last for one period and consists of two pin toggling events. | int value between 1 and 500 |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### Power Profiling Service Configuration
|
|
|
|
|
|
To use the power profiling service, define a `<powerProfilingConf>` block with the following configuration elements:
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
|
|
|
| `obsIds`* | One or more observer IDs for which this service should be used. Note that all IDs used here have to have a target configuration as well. | ID(s) of the observer(s) to use |
|
|
|
| `offset`* | Defines the start of the power measurement relative to the test start (offset in seconds). | |
|
|
|
| `duration` | Duration in seconds of the power measurement. | |
|
|
|
| `samplingRate` | Sampling rate [Hz] for the power measurement. | possible values: 1, 10, 100, 1000, 2000, 4000, 8000, 16000, 32000, 64000. default: 1000 |
|
|
|
| `fileFormat` | File format. The csv format is more convenient (text), but results in large files. If you want to parse the data manually, you can use the rld format (binary). Parsing tools are available [here](https://pypi.org/project/rocketlogger/). | possible values: csv, rld. default: csv |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
<br />
|
|
|
|
|
|
### Debug Configuration
|
|
|
|
|
|
If you want to use the debug service, define a `<debugConf>` block with the following configuration elements:
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|------------|----------------------------------------------------------------------------------------------------|---------------------------------|
|
|
|
| `obsIds`* | One or more observer IDs for which this service should be used. | ID(s) of the observer(s) to use |
|
|
|
| `gdbPort` | If specified, a GDB server will be started on the observer and listening for incoming connections.<br />**Note:** The debug server is only started 10 seconds after the scheduled test start time! | possible values: 2331 <br />**Remark:** SWV (SWO) will be available on port 2332 |
|
|
|
| `cpuSpeed` | Specifies the target CPU speed. | frequency in Hertz (default: max. native speed of target)
|
|
|
| `dataTraceConf` | Up to four blocks containing the data trace config for one global variable. | (see below) |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
Note: `gdbPort` and `dataTraceConf` are exclusive options and cannot be used simultaneously on the same observer.
|
|
|
|
|
|
##### `<dataTraceConf>`
|
|
|
|
|
|
Trace the value (32-bit) of a global variable with the ARM Cortex M4 CoreSight DWT feature.
|
|
|
|
|
|
| *Element* | *Description* | *Format* |
|
|
|
|------------|----------------------------------------------------------------------------------------------------|---------------------------------|
|
|
|
| `variable`* | Name or address of the global variable to trace. | string (in case the address is provided, it must have the prefix `0x`) |
|
|
|
| `mode` | Access mode to trace. Example: `R` (read) means only read accesses to the variable will be logged. If `PC` is appended (`R PC`), the program counter will also be recorded. | possible values: `R` (read), `W` (write), `RW` (read + write), `PC` (program counter)<br />default: `W` |
|
|
|
|
|
|
\* mandatory elements
|
|
|
|
|
|
Notes:
|
|
|
* The datatrace feature only works with ARM Cortex M4 targets, i.e. `DPP2LoRa` and `nRF5`. The target image in `<targetConf>` has to be provided in the ELF file format.
|
|
|
* Correct CPU frequency needs to be set with the `cpuSpeed` config element (see `debugConf` above).
|
|
|
* [SWO pin](Man/GpioAssignmentTargetAdapter) needs to be configured in SWO mode.
|
|
|
|