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.
• We provide a sample configuration file (including an image for the dpp (CC430 sensor node))
• Test configuration files can be validated (without being actually registered in FlockLab).
• Note that the ordering of the XML tags matters within a configuration block matters.

👉 If you have an old XML config of FlockLab 1, you can adjust the config according to this porting guide.

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 element:

<?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>: 1 element has to be specified.
2. <targetConf>: 1 or more elements have to be specified.
3. <serialConf>: 0 or more elements can be specified. Do only specify if needed.
4. <gpioTracingConf>: 0 or more elements can be specified. Do only specify if needed.
5. <gpioActuationConf>: 0 or more elements can be specified. Do only specify if needed.
6. <powerProfilingConf>: 0 or more elements can be specified. Do only specify if needed.
7. <embeddedImageConf>: 0 or more elements can be specified. Do only specify if needed.
8. <debugConf>: 0 or more elements can be specified. Do only specify if needed.

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 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

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. -> How to use obsId in the code	Observer ID(s) separated by spaces. Consult the nodelist 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>. -> How to use targetId in the code	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 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

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 to embed an image into the XML file.	base64 encoded string of exe/elf or Intel hex file

* mandatory elements

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. Note 1: In order for port swo to work, the SWD debug pins (SWDIO, SWDCLK) must not be reconfigured as output pins. 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. Notes: - If your machine only has an IPv6 address, then the XML validation will fail. - 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.

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 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

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 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

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.	possible values: csv, rld. default: csv

* mandatory elements

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. Note: The debug server is only started 10 seconds after the scheduled test start time!	possible values: 2331 Remark: SWV (SWO) will be available on port 2332
cpuSpeed	Specifies the target CPU speed. Only required (and allowed!) if dataTraceConf is used.	frequency in Hertz (default: max. native speed of target)
dataTraceConf	Config for data trace of one global variable (up to 4 dataTraceConf blocks are supported).	(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. Note: The address (or the address of the variable) must be properly aligned (i.e. the address must be an integer multiple of size) otherwise the resulting trace is unpredictable!	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) default: W
size	Size of the variable to be traced, in bytes.	integer (accepted values: 1, 2 or 4), default: 4

* 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 needs to be configured in SWO mode.