Field-Day Kit#

The field-day kit is a set of numbered scripts that the lab runs on the real Polaris during one day of data collection. This page gives the function of each script, the safety framework, the recorded data and the rehearsal against the simulator.

WARNING

Two scripts of the kit can move the real vehicle: 05_dbw_tests.py --live and 10_policy_run.py --drive. Only the lab operates the vehicle. A trained safety driver must be in the driver seat during these two scripts.

Before You Start#

You read the safety section of Calibration/Polaris/FieldDay/README.md. The file is the authority for the day on the vehicle.
For the vehicle: the lab started the vehicle stack and the NTRIP corrections with its usual procedure.
For the rehearsal on the workstation: you built the ROS 2 workspace. Refer to Build the ROS 2 Workspace.
For the rehearsal on the workstation: the DDS loopback fence is active (source ROS/Env/setup_env.sh).

The kit does not start, stop or configure the software of the vehicle. It needs Ubuntu 22.04, ROS 2 Humble and Python 3.10 with numpy and rclpy.

What the Kit Contains#

The kit is the folder Calibration/Polaris/FieldDay. On the vehicle PC the lab installs it as ~/fieldday_kit.

File	Function	Sends Commands
`00_check.sh`	Examines the ROS environment, the disk space, each necessary topic and its rate, `/tf_static` and the clock.	No
`01_wait_rtk.py`	Waits until the OxTS has an RTK fix that is stable for 30 s.	No
`02_measurements.py`	Guides the tape measurements and stores them with plausibility checks.	No
`03_record_start.sh`	Starts the two bag recorders in the background.	No
`04_runs.py`	Shows one manoeuvre card at a time and marks the start and the end of each run. A person drives.	No
`05_dbw_tests.py`	Identifies the drive-by-wire actuators with step commands. The default is a dry run.	Yes, with `--live`
`06_soil.py`	Guides the soil measurements at each test site.	No
`07_camera_check.py`	Records still images with the RTK pose for the check of the camera mount.	No
`08_summary.py`	Writes the report of the day.	No
`09_record_stop.sh`	Stops the recorders and prints the summary of each bag.	No
`10_policy_run.py`	Runs the deployment program in the shadow mode or in the drive mode.	Yes, with `--drive`
`fieldday_common.py`	Shared code: the ROS environment, the session folder, the reference places, the read-only topic monitor.	No
`Test/`	Workstation tests. This folder must not be on the vehicle PC.	Workstation only

All scripts except 05_dbw_tests.py --live and 10_policy_run.py --drive only listen to topics and write files. 10_policy_run.py belongs to the learning deployment. Refer to Deployment.

Safety Framework#

Source: 05_dbw_tests.py.

Arming#

The script sends commands only when all these conditions are true.

The operator starts the script with --live. Without this option the script prints each command and sends nothing.
The operator types three confirmations: CLOSED LOT, DRIVER READY and AREA CLEAR.
No other node publishes on the command topics. The script refuses to start while the path follower of the lab or NavRoute publishes.
The drive-by-wire reports are fresh and show no fault and no override.
The gear is correct for the test and the steering wheel is within ±45° of 0°.
The speed is below 0.1 m/s for a standstill test and below 0.6 m/s for a moving test.
The safety driver enables the drive-by-wire with the button of the vehicle.

The script then counts 3 s before the first command. The key Enter stops the count.

The script never publishes /vehicle/enable, /vehicle/disable or a gear command. The driver enables the system and moves the gear lever by hand.

Limits#

The limits are constants in the code. The options can only decrease them.

Limit	Value	Constant
Command rate	50 Hz	`RATE_HZ`
Largest steering wheel angle	180°	`SWA_MAX_DEG`
Steering steps	30°, 90°, 180° at 100 deg/s. One repeat of 90° at 300 deg/s.	`SWA_RATE_MAX`, `SWA_ACCEL`
Largest ULC speed	3 m/s	`ULC_MAX`
ULC acceleration and deceleration limit	0.8 m/s² and 1.0 m/s²	`ULC_ACCEL`, `ULC_DECEL`
Brake steps	10, 20 and 30 bar at standstill	`BRAKE_MAX_BAR`
Throttle steps	15, 20 and 25 %. Only with `--tests throttle`.	`THROTTLE_MAX`
Speed abort in a moving test	4.0 m/s	`SPEED_LIMIT_MOVING`
Speed abort in a standstill test	0.5 m/s	`SPEED_LIMIT_STATIC`
Maximum age of a report	0.25 s	`REPORT_MAX_AGE`
Time for a subsystem to engage	0.5 s	`ENGAGE_GRACE`

The ULC controls the wheel speed of the drive-by-wire, which reads approximately 7 % low. The 3 m/s step thus runs at approximately 3.3 m/s true speed. The abort speed of 4.0 m/s includes this difference.

Speed Caps#

Script	Speed Cap
`04_runs.py`	The safety note of each card. Full steering lock: 3 m/s maximum.
`05_dbw_tests.py`	ULC command 3 m/s maximum. Abort above 4.0 m/s.
`10_policy_run.py --drive`	`--speed-cap`, default 2.0 m/s, maximum 4.0 m/s.

RTK Requirement#

01_wait_rtk.py gives GO only when all these conditions are true for 30 s without a break.

/oxts/fix has the status 2 (RTK) and a horizontal sigma below 3 cm.
The height of /vehicle/odom is between 179 m and 187 m.
The messages of /oxts/fix and /vehicle/odom are fresh.
At rest, the roll and the pitch are within ±5°.

03_record_start.sh prints a note when the day has no GO. 04_runs.py marks a run with CHECK when the RTK fix covers less than 90 % of the run. 07_camera_check.py needs the RTK fix for its capture. 05_dbw_tests.py does not examine the RTK state.

Abort Conditions#

During a test the script examines these conditions at 50 Hz. Each condition stops the test immediately.

/vehicle/dbw_enabled is false or absent for 0.5 s. This is a driver override, the disable button or a fault.
A report shows an override flag, a latched override, the flag preempted or a fault flag.
A commanded subsystem reports a timeout, or it does not report enabled 0.5 s after the first command.
A report is older than 0.25 s.
/safety_stop is true.
The speed is above the limit of the test.
The steering wheel is more than 45° outside the commanded range.
The operator presses a key and Enter.
The operator presses Ctrl+C.

Safe Stop#

An abort and the normal end of a test use the same sequence.

The script sends the safe command. It is ULC 0 m/s for a moving test and a brake hold of 20 bar for a standstill test.
It holds the safe command for 0.5 s minimum. It then waits until the vehicle is stationary, 8 s maximum.
It sends one release for each subsystem (enable false).
It stops publishing. The watchdog of the drive-by-wire then releases the actuators in 0.1 s.

After an override, a disable, a fault or lost reports, the script does not wait for a stop. A second Ctrl+C stops publishing immediately. The screen shows STOPPED PUBLISHING. The driver has the vehicle and must keep a foot on the brake.

Run the Kit on the Vehicle#

The lab runs these steps on the vehicle PC. The sequence is the sequence of the numbers.

Open a terminal in the kit folder.
```
cd ~/fieldday_kit
```
Examine the vehicle PC.
```
bash 00_check.sh
```
Expected Result

Each item shows GO, WARN or NO-GO with the corrective action. The report is 00_check_<time>.txt.
Wait for the RTK fix. Drive figure-eights until the screen shows GO.
```
python3 01_wait_rtk.py
```
Record the tape measurements.
```
python3 02_measurements.py
```
Start the recorders.
```
bash 03_record_start.sh
```
Expected Result

The script shows RECORDING after it sees that the two bags grow.
Do the manoeuvres. A person drives. The drive-by-wire stays off.
```
python3 04_runs.py
```
WARNING

Obey the safety note of each card. Do not drive faster than 3 m/s at full steering lock. The vehicle can roll over.
Optional: print the plan of the drive-by-wire tests as a dry run.
```
python3 05_dbw_tests.py
```
Expected Result

The script prints each command of each test and the text DRY RUN: nothing is published.

WARNING

The next step commands the steering, the ULC and the brake of the real vehicle. Do it only on the closed ICSC lot. A trained safety driver must be in the driver seat with the seat belt on. No other person must be in the test area.
Optional: run the drive-by-wire tests on the closed lot.
```
python3 05_dbw_tests.py --live
```
Record the soil measurements at each test site.
```
python3 06_soil.py
```
Do the camera check at ICSC Parking Lot 2.
```
python3 07_camera_check.py
```
WARNING

Do not add --drive to the next command. With --drive the program commands the steering and the speed of the real vehicle. The deployment page gives the procedure for that mode.
Optional: run the deployment program in the shadow mode. A person drives and the program only listens.
```
python3 10_policy_run.py --mission F53
```
Write the report and stop the recorders.
```
python3 08_summary.py
bash 09_record_stop.sh
```
Expected Result

summary.md is in the session folder. Each bag has a file <bag>.info.txt.

You can start each script again at all times. A script does not overwrite data, and a recorder that runs stays as it is.

The Manoeuvres#

04_runs.py gives the cards in the sequence of their priority for each surface.

Surface	Priority 1	Priority 2 and 3
Parked references	60 s at the ICSC garage, which is the spawn point of the simulator	60 s near the CORS station P775
ICSC concrete lot	Circles at full lock and half lock, a slow steering sweep, brake stops	Throttle steps, constant-speed runs, reverse
Gravel lane	Constant-speed runs from 1 to 10 m/s, coast-downs in neutral, brake stops	Steering steps, a sine sweep, throttle steps
Mown grass lane	Constant-speed runs from 1 to 6 m/s, circles, coast-downs	Brake stops, throttle steps, steering sweep, reverse
Grade	The steepest lane up and down at 3 m/s with a stop	A side slope
Sensor calibration	60 s near surveyed control points	Passes near a parked car and a person, targets
Lab autonomy	One lap of the path follower of the lab	One NavRoute repeat

After each run the script shows a quality check: the duration, the RTK share, the speed and the steering range. The operator accepts the run, does it again or discards it.

What the Kit Records#

All data of one day go into one session folder, ~/fieldday/<date>. The link ~/fieldday/latest points to the newest folder.

Path	Content	Script
`session.log`	One line for each step and event	All
`00_check_<time>.txt`	The report of the check	00
`01_rtk.jsonl`, `01_rtk_result.json`	The RTK status at 1 Hz and the result	01
`measurements.json`, `tf_static.json`, `config/`	The tape measurements and the snapshots of the configuration	02
`bags/closed_loop_<time>/`	The bag of the small topics: OxTS, odometry, TF, all drive-by-wire reports and commands	03
`bags/sensors_<time>/`	The bag of the LiDAR and the camera	03
`runs.csv`, `runs/`	The markers of each run, the quality check and a 20 Hz trace	04
`dbw_tests/<time>_<test>/`	`commands.csv`, `reports.csv`, `events.log`, `result.json`	05
`soil.csv`, `soil_sites.json`	The soil measurements with the GPS position	06
`camera_check/<time>_<stance>/`	`capture.json`, `median.png`, still images, LiDAR scans, `trace.csv`	07
`summary.md`	The report of the day	08
`policy_runs/`	The reports of the deployment program	10

The sensor bag uses approximately 83 GB for each hour. The other bag uses approximately 1 GB for each hour. bash 03_record_start.sh --no-sensors records only the small bag.

result.json of a drive-by-wire test contains the step responses. For each steering step it gives the rise time and the overshoot. For each speed step it gives the time to 90 %. These logs are the input of the next fit. Refer to Calibrate against Real Logs.

Run the Same Steps against the Simulator#

The folder Test contains the rehearsal on the workstation. It runs the kit against the simulated Polaris on the same topics. The rehearsal shows that each abort path of 05_dbw_tests.py works before the day on the vehicle.

CAUTION

Do the rehearsal only inside the DDS loopback fence. The test stand publishes the report topics of the vehicle. Do not copy the folder Test to the vehicle PC.

Note

The two scripts start a simulator with the default ports. Stop all other simulators on the workstation first.

Activate the ROS 2 environment and examine the DDS loopback fence.
```
source ROS/Env/setup_env.sh
ROS/Env/check_dds_isolation.sh
```
Run the kit against the game.
```
Calibration/Polaris/FieldDay/Test/sim_run.sh ~/acres-fieldday-sim
```
The script starts the packaged game with the Polaris and the ROS 2 bridge. It then runs these steps: 00, 01, 03, one parked reference of 04, the live cases of 05, 09 and 08.
As an alternative, run the kit against ACRES Core.
```
Calibration/Polaris/FieldDay/Test/core_run.sh ~/acres-fieldday-core
```
The script starts ros2 launch acres_core_sim core_sim.launch.py in place of the game.
Read sim_cases.log and kit_steps.log in the work folder.

The live cases of step 05 against the simulator are these.

Case	Test	Action	Expected Outcome
`sim_steer_complete`	Steering steps	None	Completed
`sim_brake_complete`	Brake steps	None	Completed
`sim_ulc_complete`	ULC speed steps	None	Completed
`sim_rolling_complete`	Steering steps at 2 m/s	None	Completed
`sim_driver_disable`	Steering steps at 2 m/s	`/vehicle/disable` after 9 s	Aborted: `DBW DISABLED`
`sim_safety_stop`	ULC speed steps	`/safety_stop` after 8 s	Aborted: `/safety_stop`
`sim_reports_lost`	ULC speed steps	The bridge process stops after 8 s	Aborted: `reports lost`
`sim_operator_key`	ULC speed steps	A key after 8 s	Aborted: `operator abort`
`sim_ctrl_c`	ULC speed steps	`Ctrl`+`C` after 8 s	Aborted: `Ctrl-C`
`sim_other_publisher`	Steering steps	A second publisher on a command topic	Not started

Each case also examines commands.csv: after an abort the script sent only safe commands, then one release, then nothing.

The simulator differs from the vehicle in two results.

00_check.sh reports the simulation-time stamps and /clock as NO-GO. This is correct for a simulator.
ACRES Core has no camera. 00_check.sh reports the camera topics as absent, and the sensor bag has no images.

Other Workstation Tests#

File	Function
`Test/bag_stand.sh`	Plays the local real bags in a loop for the read-only scripts 00, 01, 02, 03, 04, 08 and 09. It never plays command topics.
`Test/fake_vehicle.py`	A substitute for the drive-by-wire with fault injection: override, fault, timeout, lost reports, safety stop.
`Test/test_dbw_safety.py`	Runs `05_dbw_tests.py --live` against the substitute through each abort path.
`Test/test_camera_check.py`	Runs 07 against the substitute and then the offline solve.
`Test/test_camera_solver.py`	Examines the offline solve of the camera mount on synthetic captures.
`Test/test_policy_run.py`, `Test/policy_core_run.sh`, `Test/policy_game_run.sh`	Tests of step 10.

After the Field Day#

The lab stops the vehicle stack. The processing team then extracts the bags on the vehicle PC and copies the results.