Messages#

The package acres_interfaces defines the messages and services of the simulator. This page lists each definition with its fields.

Generated The source is ROS/acres_interfaces/msg and ROS/acres_interfaces/srv. Run mkdocs build to generate this page again.

Topics and Services and Actions show where each definition is used. The messages of the vehicle (ds_dbw_msgs, rslidar_msg) and the standard ROS 2 packages keep their own documentation.

Definition	Kind	Description
`AgentInfo`	Message	What an agent is, sent once per episode (topic /sim/agents, transient local; in the episode log).
`AgentState`	Message	One agent after one physics step (in AgentStates, 120 Hz).
`AgentStates`	Message	Every agent after one physics step (topic /sim/agent_states in the episode log, 120 Hz).
`Agents`	Message	Every agent of the session (topic /sim/agents, transient local; in the episode log at the start of each episode).
`Conditions`	Message	Weather, clock and soil water (topic /sim/conditions in the episode log:
`EnergyLedger`	Message	Where the fuel's energy went since the agent's last reset (AcresPowerModel.h FEnergyFlows), J.
`Episode`	Message	The simulator's episode clock (topic /sim/episode, transient local; also in the episode log).
`FarmEvent`	Message	One change of the farm (crop, soil marks), as the physics step made it.
`FarmEvents`	Message	The farm changes of one physics step (topic /sim/farm_events in the episode log; only steps with events).
`FarmStamp`	Message	One ground contact the farm recorded:
`FarmStamps`	Message	The farm contacts of one physics step (topic /sim/farm_stamps in the episode log; only steps with contacts).
`FieldState`	Message	Ground truth of one field (acres/farm_state).
`TaskStatus`	Message	A task's state and reward terms (topic /sim/task; written by the task code of Learning/, not by the simulator).
`VehicleShift`	Message	A hardware shift of one vehicle (robustness studies, Self-Adaptive VLA):
`VehicleShifts`	Message	The shifts in force (topic /sim/shifts, transient local; in the episode log after every change).
`FarmState`	Service	Farm ground truth for task scoring (acres/farm_state):
`FieldQuery`	Service	Ground truth at one point (acres/field_query).
`Record`	Service	Start or stop the episode log (acres/record):
`SetConditions`	Service	Weather, clock, soil water and field restore (acres/set_conditions).
`SetVehicleShift`	Service	Set (replace) a vehicle's hardware shift (acres/set_vehicle_shift).

Message Definitions#

AgentInfo#

acres_interfaces/msg/AgentInfo

What an agent is, sent once per episode (topic /sim/agents, transient local; in the episode log).

Name	Type	Unit	Description
`name`	`string`		agent name (unique; its ROS namespace in a multi-agent session)
`vehicle`	`string`		"polaris" or "maxxum"
`implement`	`string`		Maxxum implement id ("none", "chisel_plow", ...); "" for the Polaris
`finish`	`string`		Polaris paint (graphite, forest_green, desert_tan, deep_blue); "" for the Maxxum
`body_origin_flu_m`	`geometry_msgs/Vector3`	m	the physics body origin in base_footprint (FLU), m
`wheelbase_m`	`float64`	m	front to rear axle, m
`wheel_radius_m`	`float64[4]`	m	FL, FR, RL, RR tyre radius, m
`implement_rig_names`	`string[]`		names of AgentState.implement_rig, in order (empty without an implement rig)

Definition

# What an agent is, sent once per episode (topic /sim/agents, transient local; in the episode log).
string name                       # agent name (unique; its ROS namespace in a multi-agent session)
string vehicle                    # "polaris" or "maxxum"
string implement                  # Maxxum implement id ("none", "chisel_plow", ...); "" for the Polaris
string finish                     # Polaris paint (graphite, forest_green, desert_tan, deep_blue); "" for the Maxxum
geometry_msgs/Vector3 body_origin_flu_m   # the physics body origin in base_footprint (FLU), m
float64 wheelbase_m               # front to rear axle, m
float64[4] wheel_radius_m         # FL, FR, RL, RR tyre radius, m
string[] implement_rig_names      # names of AgentState.implement_rig, in order (empty without an implement rig)

AgentState#

acres_interfaces/msg/AgentState

One agent after one physics step (in AgentStates, 120 Hz). Frame "world": the simulator's grid ENU, metres (x east, y north, z up; origin at the centre of the ACRE tile, Unreal X east / Y south / Z up at 1/100). The pose is base_footprint (the ground point below the rear axle; x forward, y left, z up), as /vehicle/odom reports it in UTM.

Name	Type	Unit	Description
`name`	`string`		agent name (AgentInfo.name)
`reset_epoch`	`uint64`		resets applied to this agent so far
`episode_time_s`	`float64`	s	simulation time since this agent's last reset, s
`pose`	`geometry_msgs/Pose`		base_footprint in world
`twist`	`geometry_msgs/Twist`		body frame (FLU): linear m/s, angular rad/s
`speed_mps`	`float64`	m/s	forward speed along the heading, m/s (negative reversing)
`steer_rad`	`float64`	rad	actual road-wheel (bicycle) angle, rad, positive left
`wheel_steer_rad`	`float64[4]`	rad	FL, FR, RL, RR steering angle, rad
`wheel_spin_rad`	`float64[4]`	rad	accumulated spin angle (for the wheels' look), rad
`wheel_omega_radps`	`float64[4]`	rad/s	spin rate, rad/s
`wheel_suspension_m`	`float64[4]`	m	mount to wheel centre extension (includes sinkage on soil), m
`wheel_slip`	`float64[4]`		longitudinal slip ratio
`wheel_sinkage_m`	`float64[4]`	m	sinkage or rut depth under the tyre, m
`wheel_normal_n`	`float64[4]`	N	ground normal load, N
`wheel_fx_n`	`float64[4]`	N	longitudinal tyre force on the chassis, N (along the wheel heading)
`wheel_fy_n`	`float64[4]`	N	lateral tyre force, N (positive toward the wheel's right)
`wheel_contact`	`bool[4]`		the wheel touches the ground (at least 1 N)
`wheel_surface`	`uint8[4]`		surface class under the wheel (SURFACE_*, AcresSurfaceMap.h ESurfaceClass)
`wheel_field`	`uint8[4]`		field id under the wheel (1..59; 0 outside fields)
`engine_rpm`	`float64`	rev/min	rev/min
`gear`	`int8`		Maxxum: 1-based forward gear (negative reverse, 0 neutral); Polaris: ds_dbw_msgs Gear value (1 P, 2 R, 3 N, 4 H, 5 L)
`throttle`	`float64`		pedal 0..1
`brake`	`float64`		pedal 0..1 (Polaris: line pressure over its 80 bar scale)
`steer_cmd_rad`	`float64`	rad	requested road-wheel angle, rad, positive left
`diff_lock`	`int8`		0 open, 1 rear, 2 rear and front
`hand_throttle`	`float64`		0..1 (Maxxum)
`dbw_enabled`	`bool`		Polaris drive-by-wire (zero for the Maxxum): ds_dbw_msgs units.
`steering_wheel_deg`	`float64`	°
`steering_cmd_deg`	`float64`	°
`steering_cmd_type`	`uint8`		SteeringCmd CMD_* of the last command
`ulc_speed_cmd_mps`	`float64`	m/s	UlcReport vel_ref
`throttle_output_pct`	`float64`	%
`brake_output_bar`	`float64`	bar
`energy`	`EnergyLedger`		Energy and fuel since the agent's last reset.
`fuel_used_l`	`float64`	L
`fuel_rate_lph`	`float64`	L/h
`mass_kg`	`float64`	kg	chassis mass with implement and payload, kg
`crop_crushed_m2`	`float64`	m²	crop this agent pushed over since its reset (tyres and body), m2
`implement_kind`	`int8`		AcresSim::EImplementKind
`implement_raised`	`bool`
`pto_on`	`bool`
`implement_depth_m`	`float64`	m
`draft_n`	`float64`	N
`pto_kw`	`float64`	kW
`hitch_lift_deg`	`float64`	°
`articulation_yaw_rad`	`float64`	rad	trailed baler about the drawbar eye, rad
`implement_rig`	`float64[]`		implement rig controls (AgentInfo.implement_rig_names)

Constant	Type	Value
`SURFACE_FIELD`	`uint8`	`0`
`SURFACE_ASPHALT`	`uint8`	`1`
`SURFACE_CONCRETE`	`uint8`	`2`
`SURFACE_GRAVEL`	`uint8`	`3`
`SURFACE_GRASS_LANE`	`uint8`	`4`
`SURFACE_GRASS`	`uint8`	`5`
`SURFACE_DIRT`	`uint8`	`6`

Definition

# One agent after one physics step (in AgentStates, 120 Hz). Frame "world": the simulator's grid ENU, metres (x east,
# y north, z up; origin at the centre of the ACRE tile, Unreal X east / Y south / Z up at 1/100). The pose is
# base_footprint (the ground point below the rear axle; x forward, y left, z up), as /vehicle/odom reports it in UTM.
string name                       # agent name (AgentInfo.name)
uint64 reset_epoch                # resets applied to this agent so far
float64 episode_time_s            # simulation time since this agent's last reset, s
geometry_msgs/Pose pose           # base_footprint in world
geometry_msgs/Twist twist         # body frame (FLU): linear m/s, angular rad/s
float64 speed_mps                 # forward speed along the heading, m/s (negative reversing)
float64 steer_rad                 # actual road-wheel (bicycle) angle, rad, positive left
float64[4] wheel_steer_rad        # FL, FR, RL, RR steering angle, rad
float64[4] wheel_spin_rad         # accumulated spin angle (for the wheels' look), rad
float64[4] wheel_omega_radps      # spin rate, rad/s
float64[4] wheel_suspension_m     # mount to wheel centre extension (includes sinkage on soil), m
float64[4] wheel_slip             # longitudinal slip ratio
float64[4] wheel_sinkage_m        # sinkage or rut depth under the tyre, m
float64[4] wheel_normal_n         # ground normal load, N
float64[4] wheel_fx_n             # longitudinal tyre force on the chassis, N (along the wheel heading)
float64[4] wheel_fy_n             # lateral tyre force, N (positive toward the wheel's right)
bool[4] wheel_contact             # the wheel touches the ground (at least 1 N)
uint8[4] wheel_surface            # surface class under the wheel (SURFACE_*, AcresSurfaceMap.h ESurfaceClass)
uint8[4] wheel_field              # field id under the wheel (1..59; 0 outside fields)
uint8 SURFACE_FIELD = 0
uint8 SURFACE_ASPHALT = 1
uint8 SURFACE_CONCRETE = 2
uint8 SURFACE_GRAVEL = 3
uint8 SURFACE_GRASS_LANE = 4
uint8 SURFACE_GRASS = 5
uint8 SURFACE_DIRT = 6
float64 engine_rpm                # rev/min
int8 gear                         # Maxxum: 1-based forward gear (negative reverse, 0 neutral); Polaris: ds_dbw_msgs
                                  # Gear value (1 P, 2 R, 3 N, 4 H, 5 L)
# Controls the vehicle model applied this step (after the drive-by-wire layer, RL bridge, scripts).
float64 throttle                  # pedal 0..1
float64 brake                     # pedal 0..1 (Polaris: line pressure over its 80 bar scale)
float64 steer_cmd_rad             # requested road-wheel angle, rad, positive left
int8 diff_lock                    # 0 open, 1 rear, 2 rear and front
float64 hand_throttle             # 0..1 (Maxxum)
# Polaris drive-by-wire (zero for the Maxxum): ds_dbw_msgs units.
bool dbw_enabled
float64 steering_wheel_deg
float64 steering_cmd_deg
uint8 steering_cmd_type           # SteeringCmd CMD_* of the last command
float64 ulc_speed_cmd_mps         # UlcReport vel_ref
float64 throttle_output_pct
float64 brake_output_bar
# Energy and fuel since the agent's last reset.
EnergyLedger energy
float64 fuel_used_l
float64 fuel_rate_lph
float64 mass_kg                   # chassis mass with implement and payload, kg
float64 crop_crushed_m2           # crop this agent pushed over since its reset (tyres and body), m2
# Maxxum implement (kind -1 without one).
int8 implement_kind               # AcresSim::EImplementKind
bool implement_raised
bool pto_on
float64 implement_depth_m
float64 draft_n
float64 pto_kw
float64 hitch_lift_deg
float64 articulation_yaw_rad      # trailed baler about the drawbar eye, rad
float64[] implement_rig           # implement rig controls (AgentInfo.implement_rig_names)

AgentStates#

acres_interfaces/msg/AgentStates

Every agent after one physics step (topic /sim/agent_states in the episode log, 120 Hz). Replay places the agents at these poses; learners read proprioception and commands from them.

Name	Type	Description
`header`	`std_msgs/Header`	stamp: simulation time after the step; frame_id "world"
`step`	`uint64`	physics steps since the world started
`agents`	`AgentState[]`

Definition

# Every agent after one physics step (topic /sim/agent_states in the episode log, 120 Hz). Replay places the agents
# at these poses; learners read proprioception and commands from them.
std_msgs/Header header            # stamp: simulation time after the step; frame_id "world"
uint64 step                       # physics steps since the world started
AgentState[] agents

Agents#

acres_interfaces/msg/Agents

Every agent of the session (topic /sim/agents, transient local; in the episode log at the start of each episode).

Name	Type	Unit	Description
`header`	`std_msgs/Header`
`agents`	`AgentInfo[]`

Definition

# Every agent of the session (topic /sim/agents, transient local; in the episode log at the start of each episode).
std_msgs/Header header
AgentInfo[] agents

Conditions#

acres_interfaces/msg/Conditions

Weather, clock and soil water (topic /sim/conditions in the episode log: at the start, after every change and once per simulated second).

Name	Type	Unit	Description
`header`	`std_msgs/Header`
`date`	`string`		local date of the environment clock, YYYY-MM-DD
`local_hour`	`float64`	h	local civil time, h
`air_temp_c`	`float64`	°C
`rain_mm_h`	`float64`	mm/h
`wind_mps`	`float64`	m/s	10 m wind, m/s
`wind_from_deg`	`float64`	°	clockwise from north
`cloud_cover`	`float64`		0..1
`visibility_m`	`float64`	m
`sun_elevation_deg`	`float64`	°
`surface_wetness`	`float64`		rain film on hard surfaces and leaves, 0..1
`weather`	`string`		preset set through set_conditions ("" = the environment's own schedule)
`soil_theta_mean`	`float64`		mean surface volumetric water content of the field cells, m3/m3
`field_ids`	`uint16[]`		fields with soil (1..59)
`field_theta`	`float64[]`		mean surface theta per field, m3/m3
`field_pond_m`	`float64[]`	m	mean pond depth per field, m

Definition

# Weather, clock and soil water (topic /sim/conditions in the episode log: at the start, after every change and
# once per simulated second).
std_msgs/Header header
string date                       # local date of the environment clock, YYYY-MM-DD
float64 local_hour                # local civil time, h
float64 air_temp_c
float64 rain_mm_h
float64 wind_mps                  # 10 m wind, m/s
float64 wind_from_deg             # clockwise from north
float64 cloud_cover               # 0..1
float64 visibility_m
float64 sun_elevation_deg
float64 surface_wetness           # rain film on hard surfaces and leaves, 0..1
string weather                    # preset set through set_conditions ("" = the environment's own schedule)
float64 soil_theta_mean           # mean surface volumetric water content of the field cells, m3/m3
uint16[] field_ids                # fields with soil (1..59)
float64[] field_theta             # mean surface theta per field, m3/m3
float64[] field_pond_m            # mean pond depth per field, m

EnergyLedger#

acres_interfaces/msg/EnergyLedger

Where the fuel's energy went since the agent's last reset (AcresPowerModel.h FEnergyFlows), J. Powertrain side: fuel -> engine loss, parasitic, PTO, hydraulic, accessory loss, engine kinetic, clutch, driveline, wheel kinetic, brake, hysteresis, slip, soil, traction (axle: informational). Chassis side (AcresSim::AccountChassis): traction -> drawbar, aero, water, lateral, suspension, chassis kinetic, potential. ground_loss_j = slip_j + lateral_j + soil_j, the energy the ground took (the scouting task's ground loss).

Name	Type	Unit
`fuel_j`	`float64`	J
`engine_loss_j`	`float64`	J
`parasitic_j`	`float64`	J
`pto_j`	`float64`	J
`hydraulic_j`	`float64`	J
`accessory_loss_j`	`float64`	J
`engine_kinetic_j`	`float64`	J
`clutch_j`	`float64`	J
`driveline_j`	`float64`	J
`wheel_kinetic_j`	`float64`	J
`brake_j`	`float64`	J
`hysteresis_j`	`float64`	J
`slip_j`	`float64`	J
`soil_j`	`float64`	J
`traction_j`	`float64`	J
`axle_j`	`float64`	J
`drawbar_j`	`float64`	J
`aero_j`	`float64`	J
`water_j`	`float64`	J
`lateral_j`	`float64`	J
`suspension_j`	`float64`	J
`chassis_kinetic_j`	`float64`	J
`potential_j`	`float64`	J
`ground_loss_j`	`float64`	J

Definition

# Where the fuel's energy went since the agent's last reset (AcresPowerModel.h FEnergyFlows), J. Powertrain side:
# fuel -> engine loss, parasitic, PTO, hydraulic, accessory loss, engine kinetic, clutch, driveline, wheel kinetic,
# brake, hysteresis, slip, soil, traction (axle: informational). Chassis side (AcresSim::AccountChassis): traction ->
# drawbar, aero, water, lateral, suspension, chassis kinetic, potential. ground_loss_j = slip_j + lateral_j + soil_j,
# the energy the ground took (the scouting task's ground loss).
float64 fuel_j
float64 engine_loss_j
float64 parasitic_j
float64 pto_j
float64 hydraulic_j
float64 accessory_loss_j
float64 engine_kinetic_j
float64 clutch_j
float64 driveline_j
float64 wheel_kinetic_j
float64 brake_j
float64 hysteresis_j
float64 slip_j
float64 soil_j
float64 traction_j
float64 axle_j
float64 drawbar_j
float64 aero_j
float64 water_j
float64 lateral_j
float64 suspension_j
float64 chassis_kinetic_j
float64 potential_j
float64 ground_loss_j

Episode#

acres_interfaces/msg/Episode

The simulator's episode clock (topic /sim/episode, transient local; also in the episode log). Sent when the simulator starts, on every reset and on every change of the simulation state.

Name	Type	Unit	Description
`header`	`std_msgs/Header`		stamp: simulation time of the event (the physics clock of /clock)
`episode_id`	`string`		unique per episode: "<session start, UTC YYYYMMDDTHHMMSS>-<episode, 4 digits>"
`episode`	`uint32`		episodes started since launch (0 until the first reset)
`reset_epoch`	`uint64`		resets applied to agent 0 since launch (the R key and the RL bridge count too)
`step`	`uint64`		physics steps (1/120 s) since the world started
`episode_time_s`	`float64`	s	simulation time since the episode began, s
`state`	`uint8`		simulation_interfaces/SimulationState: 0 stopped, 1 playing, 2 paused
`lockstep`	`bool`		the world advances only on step requests (paused between them)
`seed`	`uint64`		the sensors' noise seed (sensors.json "seed", -SensorSeed=)
`source`	`string`		"unreal" or "core": which simulator wrote it
`map`	`string`		map id, e.g. "V03ACRE"
`agents`	`string[]`		agent names in index order (agent 0 first)

Definition

# The simulator's episode clock (topic /sim/episode, transient local; also in the episode log). Sent when the
# simulator starts, on every reset and on every change of the simulation state.
std_msgs/Header header            # stamp: simulation time of the event (the physics clock of /clock)
string episode_id                 # unique per episode: "<session start, UTC YYYYMMDDTHHMMSS>-<episode, 4 digits>"
uint32 episode                    # episodes started since launch (0 until the first reset)
uint64 reset_epoch                # resets applied to agent 0 since launch (the R key and the RL bridge count too)
uint64 step                       # physics steps (1/120 s) since the world started
float64 episode_time_s            # simulation time since the episode began, s
uint8 state                       # simulation_interfaces/SimulationState: 0 stopped, 1 playing, 2 paused
bool lockstep                     # the world advances only on step requests (paused between them)
uint64 seed                       # the sensors' noise seed (sensors.json "seed", -SensorSeed=)
string source                     # "unreal" or "core": which simulator wrote it
string map                        # map id, e.g. "V03ACRE"
string[] agents                   # agent names in index order (agent 0 first)

FarmEvent#

acres_interfaces/msg/FarmEvent

One change of the farm (crop, soil marks), as the physics step made it. Positions in the world frame (ENU m).

Name	Type	Unit	Description
`kind`	`uint8`
`agent`	`string`		the agent that caused it ("" when unknown)
`field`	`uint16`		field id 1..59 (0 outside fields)
`patch`	`int32`		crop patch index (CROP_*), -1 otherwise; stable for a given map data hash
`samples`	`uint16`		CROP_: the patch's 4 x 4 sample bits set by this event (bit j 4 + i)
`flags`	`uint8`		WORKED: work flags added
`x`	`float64`	m	world east, m (CROP_*: patch origin; WORKED, RUT: cell centre)
`y`	`float64`	m	world north, m
`value`	`float64`		CROP_*: area, m2; RUT: rut depth, m; WORKED: cell area, m2

Constant	Type	Value	Description
`CROP_CRUSHED`	`uint8`	`1`	plants pushed over by tyres or the body: patch, samples newly crushed
`CROP_HARVESTED`	`uint8`	`2`	plants cut or lifted: patch, samples newly harvested
`WORKED`	`uint8`	`3`	field work on a 25 cm cell: flags (1 tilled, 2 seeded, 4 sprayed)
`RUT`	`uint8`	`4`	a rut deepened on a 25 cm cell: value = new rut depth, m
`FIELD_RESTORED`	`uint8`	`5`	a field's marks and crop damage cleared (reset): field

Definition

# One change of the farm (crop, soil marks), as the physics step made it. Positions in the world frame (ENU m).
uint8 CROP_CRUSHED = 1            # plants pushed over by tyres or the body: patch, samples newly crushed
uint8 CROP_HARVESTED = 2          # plants cut or lifted: patch, samples newly harvested
uint8 WORKED = 3                  # field work on a 25 cm cell: flags (1 tilled, 2 seeded, 4 sprayed)
uint8 RUT = 4                     # a rut deepened on a 25 cm cell: value = new rut depth, m
uint8 FIELD_RESTORED = 5          # a field's marks and crop damage cleared (reset): field
uint8 kind
string agent                      # the agent that caused it ("" when unknown)
uint16 field                      # field id 1..59 (0 outside fields)
int32 patch                       # crop patch index (CROP_*), -1 otherwise; stable for a given map data hash
uint16 samples                    # CROP_*: the patch's 4 x 4 sample bits set by this event (bit j * 4 + i)
uint8 flags                       # WORKED: work flags added
float64 x                         # world east, m (CROP_*: patch origin; WORKED, RUT: cell centre)
float64 y                         # world north, m
float64 value                     # CROP_*: area, m2; RUT: rut depth, m; WORKED: cell area, m2

FarmEvents#

acres_interfaces/msg/FarmEvents

The farm changes of one physics step (topic /sim/farm_events in the episode log; only steps with events).

Name	Type	Description
`header`	`std_msgs/Header`	stamp: simulation time of the step
`step`	`uint64`
`events`	`FarmEvent[]`

Definition

# The farm changes of one physics step (topic /sim/farm_events in the episode log; only steps with events).
std_msgs/Header header            # stamp: simulation time of the step
uint64 step
FarmEvent[] events

FarmStamp#

acres_interfaces/msg/FarmStamp

One ground contact the farm recorded: the arguments of FAcresFarmRuntime::Wheel (a tyre) or Body (the underbody sweeping tall crop), so a replay repeats the contact and redraws the crushed crop, ruts and tread prints exactly. Positions and directions in the world frame (grid ENU, m).

Name	Type	Unit	Description
`kind`	`uint8`
`agent`	`string`		the agent that made the contact
`wheel`	`int8`		0 FL, 1 FR, 2 RL, 3 RR; -1 for the body
`x`	`float64`	m	footprint centre, m
`y`	`float64`
`z`	`float64`	m	contact height, m (patches more than 1 m above or below are not touched)
`forward_x`	`float64`		unit heading along the ground
`forward_y`	`float64`
`width_m`	`float64`	m	across travel, m
`length_m`	`float64`	m	along travel this step (footprint plus distance moved), m
`pressure_pa`	`float64`		tyre ground pressure, Pa (crushing needs more than 10 kPa)
`sinkage_m`	`float64`	m	tyre sinkage, m (0 on hard ground; ruts keep 65 %)
`tyre_diameter_m`	`float64`	m	for the tread print
`clearance_m`	`float64`	m	body: underbody clearance, m (crop taller than this is pushed over)
`crushed_m2`	`float64`	m²	crop this contact pushed over, m2
`field`	`uint16`		field id under the centre (0 outside fields)

Constant	Type	Value	Description
`KIND_WHEEL`	`uint8`	`0`
`KIND_BODY`	`uint8`	`1`

Definition

# One ground contact the farm recorded: the arguments of FAcresFarmRuntime::Wheel (a tyre) or Body (the underbody
# sweeping tall crop), so a replay repeats the contact and redraws the crushed crop, ruts and tread prints exactly.
# Positions and directions in the world frame (grid ENU, m).
uint8 KIND_WHEEL = 0
uint8 KIND_BODY = 1
uint8 kind
string agent                      # the agent that made the contact
int8 wheel                        # 0 FL, 1 FR, 2 RL, 3 RR; -1 for the body
float64 x                         # footprint centre, m
float64 y
float64 z                         # contact height, m (patches more than 1 m above or below are not touched)
float64 forward_x                 # unit heading along the ground
float64 forward_y
float64 width_m                   # across travel, m
float64 length_m                  # along travel this step (footprint plus distance moved), m
float64 pressure_pa               # tyre ground pressure, Pa (crushing needs more than 10 kPa)
float64 sinkage_m                 # tyre sinkage, m (0 on hard ground; ruts keep 65 %)
float64 tyre_diameter_m           # for the tread print
float64 clearance_m               # body: underbody clearance, m (crop taller than this is pushed over)
float64 crushed_m2                # crop this contact pushed over, m2
uint16 field                      # field id under the centre (0 outside fields)

FarmStamps#

acres_interfaces/msg/FarmStamps

The farm contacts of one physics step (topic /sim/farm_stamps in the episode log; only steps with contacts).

Name	Type	Description
`header`	`std_msgs/Header`	stamp: simulation time of the step
`step`	`uint64`
`stamps`	`FarmStamp[]`

Definition

# The farm contacts of one physics step (topic /sim/farm_stamps in the episode log; only steps with contacts).
std_msgs/Header header            # stamp: simulation time of the step
uint64 step
FarmStamp[] stamps

FieldState#

acres_interfaces/msg/FieldState

Ground truth of one field (acres/farm_state). Areas in m2.

Name	Type	Unit	Description
`field`	`uint16`		field id 1..59
`name`	`string`		"F01".."F59"
`crop`	`string`		"corn", "soybean", "potato" or "" (no crop)
`crop_area_m2`	`float64`	m²	area of the field's crop patches
`crushed_m2`	`float64`	m²	crop crushed so far
`crushed_in_band_m2`	`float64`	m²	of which within edge_band_m of the field's edge (the allowed band)
`crushed_out_band_m2`	`float64`	m²	of which farther in (not allowed)
`harvested_m2`	`float64`	m²
`tilled_m2`	`float64`	m²
`seeded_m2`	`float64`	m²
`sprayed_m2`	`float64`	m²
`theta_mean`	`float64`		mean surface volumetric water content, m3/m3 (-1 without soil cells)
`pond_mean_m`	`float64`	m	mean pond depth, m
`rut_area_m2`	`float64`	m²	25 cm cells with a rut deeper than 1 cm

Definition

# Ground truth of one field (acres/farm_state). Areas in m2.
uint16 field                      # field id 1..59
string name                       # "F01".."F59"
string crop                       # "corn", "soybean", "potato" or "" (no crop)
float64 crop_area_m2              # area of the field's crop patches
float64 crushed_m2                # crop crushed so far
float64 crushed_in_band_m2        # of which within edge_band_m of the field's edge (the allowed band)
float64 crushed_out_band_m2       # of which farther in (not allowed)
float64 harvested_m2
float64 tilled_m2
float64 seeded_m2
float64 sprayed_m2
float64 theta_mean                # mean surface volumetric water content, m3/m3 (-1 without soil cells)
float64 pond_mean_m               # mean pond depth, m
float64 rut_area_m2               # 25 cm cells with a rut deeper than 1 cm

TaskStatus#

acres_interfaces/msg/TaskStatus

A task's state and reward terms (topic /sim/task; written by the task code of Learning/, not by the simulator).

Name	Type	Description
`header`	`std_msgs/Header`
`task`	`string`	task id, e.g. "scouting"
`instruction`	`string`	the language instruction, if any
`names`	`string[]`	reward term names
`values`	`float64[]`	reward term values this step
`reward`	`float64`	total reward this step
`done`	`bool`
`success`	`bool`

Definition

# A task's state and reward terms (topic /sim/task; written by the task code of Learning/, not by the simulator).
std_msgs/Header header
string task                       # task id, e.g. "scouting"
string instruction                # the language instruction, if any
string[] names                    # reward term names
float64[] values                  # reward term values this step
float64 reward                    # total reward this step
bool done
bool success

VehicleShift#

acres_interfaces/msg/VehicleShift

A hardware shift of one vehicle (robustness studies, Self-Adaptive VLA): offsets added to the actuators and the sensor mounts, with a label for datasets. All zero = the vehicle as calibrated.

Name	Type	Unit	Description
`agent`	`string`		agent name
`label`	`string`		free text for datasets, e.g. "steer+3deg"
`steering_offset_deg`	`float64`	°	added to the steering wheel angle the steering actuator holds (Polaris, deg of steering wheel); Maxxum: road-wheel offset, deg
`ulc_speed_bias_mps`	`float64`	m/s	added to the speed the ULC measures (the vehicle settles this much slower), m/s
`throttle_bias_pct`	`float64`	%	added to the throttle actuator output, % pedal
`brake_bias_bar`	`float64`	bar	added to the brake actuator output, bar
`camera_offset_m`	`geometry_msgs/Vector3`	m	camera mount translation added, base_footprint FLU, m
`camera_offset_rpy_deg`	`geometry_msgs/Vector3`	°	camera mount rotation added (roll, pitch, yaw), deg
`lidar_offset_m`	`geometry_msgs/Vector3`	m	LiDAR mount translation added, m
`lidar_offset_rpy_deg`	`geometry_msgs/Vector3`	°	LiDAR mount rotation added, deg

Definition

# A hardware shift of one vehicle (robustness studies, Self-Adaptive VLA): offsets added to the actuators and the
# sensor mounts, with a label for datasets. All zero = the vehicle as calibrated.
string agent                      # agent name
string label                      # free text for datasets, e.g. "steer+3deg"
float64 steering_offset_deg       # added to the steering wheel angle the steering actuator holds (Polaris, deg of
                                  # steering wheel); Maxxum: road-wheel offset, deg
float64 ulc_speed_bias_mps        # added to the speed the ULC measures (the vehicle settles this much slower), m/s
float64 throttle_bias_pct         # added to the throttle actuator output, % pedal
float64 brake_bias_bar            # added to the brake actuator output, bar
geometry_msgs/Vector3 camera_offset_m     # camera mount translation added, base_footprint FLU, m
geometry_msgs/Vector3 camera_offset_rpy_deg   # camera mount rotation added (roll, pitch, yaw), deg
geometry_msgs/Vector3 lidar_offset_m      # LiDAR mount translation added, m
geometry_msgs/Vector3 lidar_offset_rpy_deg    # LiDAR mount rotation added, deg

VehicleShifts#

acres_interfaces/msg/VehicleShifts

The shifts in force (topic /sim/shifts, transient local; in the episode log after every change).

Name	Type	Unit	Description
`header`	`std_msgs/Header`
`shifts`	`VehicleShift[]`

Definition

# The shifts in force (topic /sim/shifts, transient local; in the episode log after every change).
std_msgs/Header header
VehicleShift[] shifts

Service Definitions#

FarmState#

acres_interfaces/srv/FarmState

Farm ground truth for task scoring (acres/farm_state): per field crop damage (split at the allowed edge band), field work, soil water.

Request

Name	Type	Unit	Description
`edge_band_m`	`float64`	m	width of the allowed band inside each field's edge, m (0: everything is out)
`fields`	`uint16[]`		fields to report (empty: every field with crop or marks)

Response

Name	Type	Unit	Description
`result`	`simulation_interfaces/Result`
`header`	`std_msgs/Header`
`fields`	`FieldState[]`
`crushed_m2`	`float64`	m²	crop crushed on the whole farm since the start
`harvested_kg`	`float64`	kg

Definition

# Farm ground truth for task scoring (acres/farm_state): per field crop damage (split at the allowed edge band),
# field work, soil water.
float64 edge_band_m               # width of the allowed band inside each field's edge, m (0: everything is out)
uint16[] fields                   # fields to report (empty: every field with crop or marks)
---
simulation_interfaces/Result result
std_msgs/Header header
FieldState[] fields
float64 crushed_m2                # crop crushed on the whole farm since the start
float64 harvested_kg

FieldQuery#

acres_interfaces/srv/FieldQuery

Ground truth at one point (acres/field_query).

Request

Name	Type	Description
`frame_id`	`string`	"world" (grid ENU m, default) or "utm" (UTM 16N easting, northing)
`x`	`float64`
`y`	`float64`

Response

Name	Type	Unit	Description
`result`	`simulation_interfaces/Result`
`field`	`uint16`		field id (0 outside fields)
`surface`	`string`		surface class under the point (asphalt, concrete, gravel, soil, sod, ...)
`ground_z`	`float64`		ground height, world m
`theta`	`float64`		surface volumetric water content, m3/m3 (-1 on pavement)
`pond_m`	`float64`	m	standing water, m
`rut_m`	`float64`	m	rut depth, m
`worked`	`uint8`		work flags (1 tilled, 2 seeded, 4 sprayed)
`crop`	`string`		crop of the nearest patch within 1 m ("" none)
`crop_crushed`	`float64`		its crushed fraction, 0..1
`edge_distance_m`	`float64`	m	distance to the field's edge, m (inside positive; 0 outside fields)

Definition

# Ground truth at one point (acres/field_query).
string frame_id                   # "world" (grid ENU m, default) or "utm" (UTM 16N easting, northing)
float64 x
float64 y
---
simulation_interfaces/Result result
uint16 field                      # field id (0 outside fields)
string surface                    # surface class under the point (asphalt, concrete, gravel, soil, sod, ...)
float64 ground_z                  # ground height, world m
float64 theta                     # surface volumetric water content, m3/m3 (-1 on pavement)
float64 pond_m                    # standing water, m
float64 rut_m                     # rut depth, m
uint8 worked                      # work flags (1 tilled, 2 seeded, 4 sprayed)
string crop                       # crop of the nearest patch within 1 m ("" none)
float64 crop_crushed              # its crushed fraction, 0..1
float64 edge_distance_m           # distance to the field's edge, m (inside positive; 0 outside fields)

Record#

acres_interfaces/srv/Record

Start or stop the episode log (acres/record): an MCAP file with the agent states at the physics rate, the farm events, conditions, shifts and the episode clock (Documentation/Reference/episode-log.md).

Request

Name	Type	Unit	Description
`action`	`uint8`
`path`	`string`		START: output .mcap (absolute; "" = <session folder>/episode-<n>.mcap)

Constant	Type	Value	Description
`START`	`uint8`	`1`
`STOP`	`uint8`	`2`

Response

Name	Type	Unit	Description
`result`	`simulation_interfaces/Result`
`path`	`string`		the file written
`messages`	`uint64`		messages written so far
`duration_s`	`float64`	s	simulation time covered, s

Definition

# Start or stop the episode log (acres/record): an MCAP file with the agent states at the physics rate, the farm
# events, conditions, shifts and the episode clock (Documentation/Reference/episode-log.md).
uint8 START = 1
uint8 STOP = 2
uint8 action
string path                       # START: output .mcap (absolute; "" = <session folder>/episode-<n>.mcap)
---
simulation_interfaces/Result result
string path                       # the file written
uint64 messages                   # messages written so far
float64 duration_s                # simulation time covered, s

SetConditions#

acres_interfaces/srv/SetConditions

Weather, clock, soil water and field restore (acres/set_conditions). Each part applies only when its set_* flag is true. Applied between physics steps; the new conditions are logged on /sim/conditions.

Request

Name	Type	Unit	Description
`set_clock`	`bool`
`date`	`string`		YYYY-MM-DD (local)
`local_hour`	`float64`		h
`set_weather`	`bool`
`weather`	`string`		preset: "clear", "fair", "overcast", "rain", "storm", "fog" ("" keeps the sky)
`rain_mm_h`	`float64`	mm/h	rain rate, mm/h (negative: the preset's)
`set_soil_water`	`bool`
`soil_wetness`	`float64`		0 = as dry as the field's wilting point, 1 = saturated (surface layer)
`soil_fields`	`uint16[]`		fields to wet or dry (empty: every field)
`restore_fields`	`bool`
`fields`	`uint16[]`		fields whose marks and crop damage are cleared (empty: every field)

Response

Name	Type	Unit	Description
`result`	`simulation_interfaces/Result`
`message`	`string`

Definition

# Weather, clock, soil water and field restore (acres/set_conditions). Each part applies only when its set_* flag is
# true. Applied between physics steps; the new conditions are logged on /sim/conditions.
bool set_clock
string date                       # YYYY-MM-DD (local)
float64 local_hour                # h
bool set_weather
string weather                    # preset: "clear", "fair", "overcast", "rain", "storm", "fog" ("" keeps the sky)
float64 rain_mm_h                 # rain rate, mm/h (negative: the preset's)
bool set_soil_water
float64 soil_wetness              # 0 = as dry as the field's wilting point, 1 = saturated (surface layer)
uint16[] soil_fields              # fields to wet or dry (empty: every field)
bool restore_fields
uint16[] fields                   # fields whose marks and crop damage are cleared (empty: every field)
---
simulation_interfaces/Result result
string message

SetVehicleShift#

acres_interfaces/srv/SetVehicleShift

Set (replace) a vehicle's hardware shift (acres/set_vehicle_shift). An all-zero shift restores the vehicle.

Request

Name	Type	Unit	Description
`shift`	`VehicleShift`

Response

Name	Type	Unit	Description
`result`	`simulation_interfaces/Result`

Definition

# Set (replace) a vehicle's hardware shift (acres/set_vehicle_shift). An all-zero shift restores the vehicle.
VehicleShift shift
---
simulation_interfaces/Result result