Roost

Roost is the solar mobile poultry house that moves itself to fresh grass. It reports to Roots as a device of type roost and takes commands from the dashboard, the API, the CLI, the MCP server and the panel on its rear gable.

What it reports

Metric	Unit	What
`feed.bin_pct`	%	Feed left in the bin on the hitch platform.
`feed.dispensed_kg`	kg	Feed the augers delivered since the last report.
`water.tank_pct`	%	Header tank or trough level.
`water.used_l`	L	Water used since the last report.
`climate.temp_c`	°C	Air temperature at bird height (highest pod) or at the station.
`climate.humidity_pct`	%	Relative humidity.
`climate.nh3_ppm`	ppm	Ammonia at bird height (highest pod).
`climate.co2_ppm`	ppm	Carbon dioxide at bird height (highest pod).
`power.battery_pct`	%	House battery state of charge.
`power.solar_w`	W	Solar input from the roof.
`power.load_w`	W	Total electrical load.
`move.distance_m`	m	Distance moved since the last report.
`birds.inside`	birds	Birds counted inside by the door vision pods.

Roost also keeps a state object: each of the 14 pop doors, the door schedule, the move (stepping or stopped, metres a day, heading), spine height, climate mode and target, awnings, fans, the six heater panels, the winter floor and lights.

roots roost

GET /v1/farms/{farm}/roosts

Commands

Command	Parameters	What
`doors.open`	`doors`: "all" or a list of door numbers 1-14	Open pop doors. The vision pods still close a door on any predator.
`doors.close`	`doors`: "all" or a list of door numbers 1-14	Close pop doors.
`doors.schedule`	`open`: HH:MM or "dawn" `close`: HH:MM or "dusk"	Set the open and close times. Doors close at dusk unless set.
`move.start`	`meters_per_day`: number, default one house length (18) `heading_deg`: optional compass heading	Start moving to fresh grass in small steps through the day.
`move.stop`	—	Stop the drive.
`move.to_paddock`	`paddock_id`: paddock id	Plan the route to a paddock and move there at the set rate.
`feed.dispense`	`kg`: number	Run the augers to fill the pans.
`feed.schedule`	`times`: list of HH:MM	Set feeding times.
`spines.set_height`	`mm`: number above the floor `mode`: "auto" to follow flock age	Set the feed and water spine height so the pan lip sits at the birds’ backs.
`climate.set_mode`	`mode`: "auto" \| "summer" \| "winter"	Ventilation mode.
`climate.set_target`	`temp_c`: number	Target temperature for the inside air at bird height.
`awnings.set`	`position`: "open" \| "closed" \| "auto"	Open or close the awning panes.
`fans.set`	`tunnel`: "on" \| "off" \| "auto" `ridge`: "on" \| "off" \| "auto"	Tunnel and ridge fans.
`heaters.set`	`mode`: "on" \| "off" \| "auto" `panels`: optional list of panel numbers 1-6	Radiant brooder panels.
`floor.deploy`	—	Roll out the winter floor.
`floor.retract`	—	Roll the winter floor back onto its drums.
`lights.set`	`mode`: "on" \| "off" \| "auto"	Interior lights and the spine hairline.

roots roost doors.close doors=all
roots roost feed.dispense kg=20
roots roost climate.set_mode mode=winter
roots roost move.to_paddock paddock_id=pad_…

POST /v1/devices/{roost}/commands
{ "command": "heaters.set", "params": { "mode": "auto" } }

A command is queued until the Roost picks it up on its next report, delivered once it has it, then done or failed with a result. On the sample farm, commands apply straight away and come back done with "simulated": true.

Ask before moving a house or opening doors after dark. The MCP server tells assistants the same.

Alerts

Roots watches every report and opens an alert when a reading crosses a line, then resolves it when the reading comes back. The defaults are below; change them per farm in settings.rules.

Rule	Metric	Watch	Urgent	Clears at
`roost.ammonia`	`climate.nh3_ppm`	≥ 20	≥ 25	15
`roost.heat`	`climate.temp_c`	≥ 32	≥ 35	30
`roost.feed`	`feed.bin_pct`	≤ 15	≤ 5	25
`water.level`	`water.tank_pct`	≤ 20	≤ 5	30
`roost.battery`	`power.battery_pct`	≤ 20	≤ 8	30
`animal.fever`	`body.temp_c`	≥ 40	≥ 40.6	39.6
`device.battery`	`device.battery_pct`	≤ 15	—	25

Roost events open alerts straight away: predator.detected, safety_edge.stop, door.jammed.

PATCH /v1/farms/{farm}
{ "settings": { "rules": { "roost.ammonia": { "watch": 15, "urgent": 20, "clear": 10 } } } }