{
    "key": "hc-sr04-level",
    "kind": "sensor",
    "model": {
        "aliases": [
            "hc-sr04-level"
        ]
    },
    "driver": {
        "runtime": {
            "init": {
                "args": {
                    "echo_pin": "board.D{echo_pin}",
                    "trigger_pin": "board.D{trig_pin}"
                },
                "class": "adafruit_hcsr04.HCSR04"
            },
            "apt_packages": [],
            "pip_packages": [
                "adafruit-circuitpython-hcsr04"
            ],
            "python_module": "drivers.hcsr04"
        },
        "targets": [
            "raspberrypi"
        ],
        "verified": {
            "by": null,
            "os": null,
            "date": null,
            "board": null,
            "reviewed_by": null,
            "evidence_url": null
        },
        "interface": "gpio-timing",
        "connection": {
            "pins": [
                {
                    "role": "trig",
                    "notes": null,
                    "required": true
                },
                {
                    "role": "echo",
                    "notes": "Outputs 5V. Must be divided or level shifted to 3.3V before reaching a GPIO input.",
                    "required": true
                }
            ],
            "supply_voltage": "5V",
            "level_shift_required": "Required on echo"
        },
        "constraints": {
            "warmup_seconds": null,
            "read_timeout_seconds": 1,
            "min_read_interval_seconds": 0.06
        },
        "failure_modes": [
            "The echo pin idles at 5V. Connecting it directly to a Raspberry Pi GPIO will damage the pin. A divider or level shifter is mandatory.",
            "Level percent is derived from distance and requires the empty and full distances to be configured per installation. Without them the reading is meaningless.",
            "Condensation on the transducer face in a tank headspace causes sustained misreads.",
            "Foam and turbulent surfaces scatter the pulse and produce no echo."
        ]
    },
    "source": "platform-seed",
    "status": "draft",
    "platform": {
        "name": "HC-SR04 Liquid Level (Ultrasonic)",
        "protocol": "gpio",
        "readings": [
            {
                "slug": "level-percent",
                "unit": "percent",
                "label": "Level",
                "data_type": "float",
                "range_max": 100,
                "range_min": 0,
                "unit_symbol": "%",
                "device_class": null,
                "decimal_places": 1,
                "threshold_crit_low": 10,
                "threshold_warn_low": 20,
                "threshold_crit_high": 100,
                "threshold_warn_high": 95
            }
        ],
        "description": "Ultrasonic sensor repurposed for non-contact liquid level measurement in tanks. GPIO echo timing.",
        "sensor_type": "fluid",
        "manufacturer": null,
        "model_number": "HC-SR04-LEVEL",
        "datasheet_url": null,
        "read_interval_seconds": 30
    },
    "revision": 1
}