Greenhouse Vent Tutorial

This tutorial walks through building an automated greenhouse vent simulation: a thermostat controller reads temperature and commands a servo; a position sensor reports how far the vent is open. By the end you will have:

Defined a custom signal type (VentAngle)
Written two custom components from scratch
Wired a multi-component simulation graph
Run steady-state and transient simulations
Added per-run I/O logging (export_telemetry)
Optionally trained a hosted ML model from measurements
Wrapped everything into a reusable composite component

All code is executable. No hardware required.

The system

(ambient temp) ──▶ [ThermostatController] ──pwm──▶ [ServoMotor] ──▶ [VentPositionSensor] ──▶ vent angle

A real greenhouse would also include a TemperatureSensor, ADC, and power supply. This tutorial feeds temperature directly into the controller so you can focus on component authoring and graph wiring.

1. Project setup

pip install hardwave

import hardwave
import hardwave.stdlib

2. Custom type: VentAngle

from hardwave.types import HardwaveType, TypeRegistry

VentAngle = HardwaveType(
    name="VentAngle",
    unit="°",
    description="Greenhouse vent opening angle",
    min_value=0.0,
    max_value=90.0,
)
TypeRegistry.instance().register(VentAngle)

3. ThermostatController

Maps temperature linearly to vent openness (0-1) and encodes it as a 50 Hz PWM signal:

from hardwave.components import Component, ComponentMeta, ComponentRegistry, Parameter
from hardwave.ports import input_port, output_port

class ThermostatController(Component):
    meta = ComponentMeta(
        name="ThermostatController",
        display_name="Greenhouse Thermostat Controller",
        version="1.0.0",
        description="Converts temperature to a servo PWM command",
        category="Control",
    )
    ports = [
        input_port("temperature", "Temperature", "Ambient air temperature (°C)"),
        output_port("vent_state", "ControlSignal", "Vent openness: 0.0 = shut, 1.0 = fully open"),
        output_port("pwm_out",    "PWMSignal",     "50 Hz PWM signal for the servo"),
    ]
    parameters = [
        Parameter("t_min", "Lower Threshold", "°C", float, 20.0),
        Parameter("t_max", "Upper Threshold", "°C", float, 35.0),
    ]

    def solve(self, inputs: dict) -> dict:
        T = inputs["temperature"]
        t_min, t_max = self.get_param("t_min"), self.get_param("t_max")
        openness = max(0.0, min(1.0, (T - t_min) / (t_max - t_min)))
        duty = (1.0 + openness * 0.5) / 20.0
        return {
            "vent_state": openness,
            "pwm_out": {"frequency_hz": 50.0, "duty_cycle": duty},
        }

ComponentRegistry.instance().register(ThermostatController)

4. VentPositionSensor

import math

class VentPositionSensor(Component):
    meta = ComponentMeta(
        name="VentPositionSensor",
        display_name="Vent Position Sensor",
        version="1.0.0",
        description="Converts servo angle (rad) to vent angle (degrees)",
        category="Sensors",
    )
    ports = [
        input_port("servo_angle_rad", "AngularPosition", "Servo shaft angle (rad)"),
        output_port("vent_angle_deg", "VentAngle",      "Vent opening angle (°)"),
        output_port("is_open",        "BooleanSignal",   "True if vent > 5° open"),
    ]
    parameters = [
        Parameter("gear_ratio", "Gear Ratio", "-", float, 1.0),
    ]

    def solve(self, inputs: dict) -> dict:
        degrees = math.degrees(inputs["servo_angle_rad"]) * self.get_param("gear_ratio")
        degrees = max(0.0, min(90.0, degrees))
        return {"vent_angle_deg": degrees, "is_open": 1 if degrees > 5.0 else 0}

ComponentRegistry.instance().register(VentPositionSensor)

5. Wire the graph

from hardwave.simulation import SimulationGraph, SimulationEngine
from hardwave.stdlib.components.motors import ServoMotor

graph = SimulationGraph()
graph.add_component(ThermostatController("ctrl", param_values={"t_min": 20.0, "t_max": 35.0}))
graph.add_component(ServoMotor("servo"))
graph.add_component(VentPositionSensor("pos_sensor"))

graph.connect("ctrl", "pwm_out", "servo", "pwm_signal")
graph.connect("servo", "angular_position", "pos_sensor", "servo_angle_rad")

graph.validate(external_inputs={
    "ctrl":  {"temperature": 28.0},
    "servo": {"load_torque": 0.0},
})

Fan-out vs fan-in. One output can connect to many inputs (fan-out) on any port. Multiple outputs into one input (fan-in) requires aggregating_input_port() on the target. See Aggregating Input Ports.

6. Steady-state sweep

engine = SimulationEngine(graph)

for T in [18.0, 22.0, 25.0, 27.5, 30.0, 35.0, 40.0]:
    r = engine.run(inputs={"ctrl": {"temperature": T}, "servo": {"load_torque": 0.0}})
    openness = r.get_output("ctrl", "vent_state")
    angle    = r.get_output("pos_sensor", "vent_angle_deg")
    print(f"{T:>5.1f}°C  openness={openness:.0%}  angle={angle:.1f}°")

7. Composite assembly

Package the full control loop as a single reusable component. See Composite Components for the BuildContext API.

from hardwave.components import CompositeComponent, BuildContext
from hardwave.components.composite import Connection

class GreenhouseVentAssembly(CompositeComponent):
    meta = ComponentMeta(
        name="GreenhouseVentAssembly",
        display_name="Greenhouse Vent Assembly",
        version="1.0.0",
        description="Autonomous vent: reads temperature, drives servo, reports angle",
        category="Greenhouse",
    )
    ports = [
        input_port("temperature",  "Temperature",  "Ambient air temperature"),
        input_port("load_torque",  "Torque",       "Load on servo shaft",
                   required=False, default=0.0),
        output_port("vent_angle_deg", "VentAngle",     "Vent angle (°)"),
        output_port("vent_state",     "ControlSignal", "Openness 0-1"),
        output_port("is_open",        "BooleanSignal", "True if vent > 5°"),
    ]
    parameters = [
        Parameter("t_min", "Lower Threshold", "°C", float, 20.0),
        Parameter("t_max", "Upper Threshold", "°C", float, 35.0),
    ]

    def build(self, ctx: BuildContext) -> None:
        ctx.add(ThermostatController("_ctrl", param_values={
            "t_min": self.get_param("t_min"),
            "t_max": self.get_param("t_max"),
        }))
        ctx.add(ServoMotor("_servo"))
        ctx.add(VentPositionSensor("_pos"))

        ctx.connect(Connection("_ctrl",  "pwm_out",          "_servo", "pwm_signal"))
        ctx.connect(Connection("_servo", "angular_position", "_pos",   "servo_angle_rad"))

        ctx.map_input("temperature", "_ctrl",  "temperature")
        ctx.map_input("load_torque", "_servo", "load_torque")
        ctx.map_output("vent_angle_deg", "_pos",  "vent_angle_deg")
        ctx.map_output("vent_state",     "_ctrl", "vent_state")
        ctx.map_output("is_open",        "_pos",  "is_open")

ComponentRegistry.instance().register(GreenhouseVentAssembly)

Use it as a drop-in single component:

graph2 = SimulationGraph()
graph2.add_component(GreenhouseVentAssembly("vent", param_values={"t_min": 20.0, "t_max": 35.0}))
result = SimulationEngine(graph2).run(inputs={"vent": {"temperature": 30.0}})
print(result.get_output("vent", "vent_angle_deg"))  # 60.0°

What you learned

Concept	Where
Custom signal types	`VentAngle`
Component definition	`ThermostatController`, `VentPositionSensor`
Graph assembly	`SimulationGraph.add_component()`, `.connect()`
Steady-state simulation	`engine.run()` + temperature sweep
Transient simulation	`SimulationDomain.TRANSIENT` (see Transient Simulation)
Hosted ML models	`hardwave.premium.create_model` / `append_records` / `train_model` (see Hosted ML models)
Composite components	`GreenhouseVentAssembly`
Serialization	`graph.to_dict()` (see Saving Graphs)
Cloud snapshots	`graph.save(..., result=result)` (attach run outputs for the dashboard RESULTS tab)
Component faults	Component Faults and Health (motor thermal runaway, battery over-discharge)

The full step-by-step tutorial with hosted ML models, transient, and fault examples is in the TUTORIAL.md file in the Hardwave repository.

Getting Started

Guides

Simulation

Reference

Greenhouse Vent Tutorial

The system

1. Project setup

2. Custom type: VentAngle

3. ThermostatController

4. VentPositionSensor

5. Wire the graph

6. Steady-state sweep

7. Composite assembly

What you learned

​The system

​1. Project setup

​2. Custom type: VentAngle

​3. ThermostatController

​4. VentPositionSensor

​5. Wire the graph

​6. Steady-state sweep

​7. Composite assembly

​What you learned

The system

1. Project setup

2. Custom type: VentAngle

3. ThermostatController

4. VentPositionSensor

5. Wire the graph

6. Steady-state sweep

7. Composite assembly

What you learned