# HIL-OS Examples

A comprehensive collection of example programs for the **HIL-OS** (Hardware-in-the-Loop Operating System) LISP language. These examples demonstrate every feature of the language, from basic I/O to advanced projects.

## Quick Start

```bash
# Run any example headlessly (no hardware needed):
hil-cli simulate 01-getting-started/hello-world.hil

# Run on real Arduino via serial:
hil-cli run 01-getting-started/blink.hil

# Transpile to Arduino C and open in CRUMB simulator:
hil-cli crumb 08-projects/morse-sos.hil --open
```

## Directory Structure

```
examples/
├── 01-getting-started/    Basic programs for beginners
│   ├── hello-world.hil    First program
│   ├── blink.hil          Classic LED blink
│   └── variables.hil      Variables and assignment
│
├── 02-operators/          All language operators
│   ├── arithmetic.hil     + - * / %
│   ├── comparison.hil     == != > < <= >=
│   ├── boolean-logic.hil  AND OR NOT
│   └── math-functions.hil MAP CONSTRAIN RANDOM MIN MAX ABS
│
├── 03-control-flow/       Loops and conditionals
│   ├── if-else.hil        IF branching
│   ├── cond-multi-branch.hil  COND (multi-way)
│   ├── while-loop.hil     WHILE loops
│   ├── for-loop.hil       FOR counter loops
│   └── break-continue.hil BREAK/CONTINUE
│
├── 04-functions/          DEFUN and recursion
│   ├── defun-basics.hil   Define and call functions
│   └── recursion.hil      Recursive algorithms
│
├── 05-sensors/            Sensor input examples
│   ├── lm35-temperature.hil   LM35 thermometer
│   ├── ldr-night-light.hil    Light-dependent resistor
│   ├── ultrasonic-distance.hil  HC-SR04 distance
│   └── dht-humidity.hil       DHT22 temp/humidity
│
├── 06-actuators/          Output and control
│   ├── servo-sweep.hil        Servo motor sweep
│   ├── pwm-fan-control.hil    PWM fan with temperature
│   ├── relay-switch.hil       Relay toggle with button
│   └── neopixel-colors.hil    NeoPixel color cycle
│
├── 07-communication/      Protocols and displays
│   ├── i2c-rtc.hil            I2C RTC communication
│   └── lcd-display.hil        16x2 LCD display
│
└── 08-projects/           Complete real-world projects
    ├── morse-sos.hil          Morse code beacon
    ├── thermostat.hil         Digital thermostat
    ├── parking-sensor.hil     Car parking sensor
    ├── fibonacci-music.hil    Algorithmic music
    ├── robot-arm.hil          3-DOF robotic arm
    ├── data-logger.hil        SD card data logging
    ├── pid-controller.hil     PID temperature control
    ├── interrupt-driven-system.hil  Hardware interrupts
    ├── state-machine.hil      Traffic light controller
    └── menu-system.hil        Interactive serial menu
```

## Language Reference

### Operators

| Category | Operators |
|----------|-----------|
| Arithmetic | `+` `-` `*` `/` `%` |
| Comparison | `==` `!=` `>` `<` `<=` `>=` |
| Boolean | `AND` `OR` `NOT` |
| Math | `MAP` `CONSTRAIN` `RANDOM` `MIN` `MAX` `ABS` |

### Control Flow

| Form | Description |
|------|-------------|
| `(IF cond then else?)` | Conditional |
| `(COND (test expr)... (1 default))` | Multi-branch |
| `(WHILE cond body...)` | Loop |
| `(FOR var from to body...)` | Counter loop |
| `(BREAK)` | Exit innermost loop |
| `(CONTINUE)` | Skip to next iteration |

### I/O

| Form | Description |
|------|-------------|
| `(WRITE D/A/P pin val)` | Digital/Analog/PWM write |
| `(READ D/A pin)` | Digital/Analog read |
| `(TOGGLE pin)` | Toggle digital pin |
| `(TONE pin freq dur)` | Play tone |
| `(PULSE pin count us)` | Microsecond pulse |
| `(BLINK pin count ms)` | LED blink |
| `(PIN-MODE pin mode)` | Set pin mode (0=INPUT, 1=OUTPUT, 2=PULLUP) |
| `(MILLIS)` | Current time in ms |
| `(DELAY ms)` | Wait |
| `(DLY-US us)` | Microsecond delay |
| `(LOG msg...)` | Print to serial |

### Functions

| Form | Description |
|------|-------------|
| `(DEFUN name (args...) body...)` | Define function |
| `(name args...)` | Call function |

### Sensors

| Form | Description |
|------|-------------|
| `(LM35 pin)` | Temperature in Celsius |
| `(ULTRASONIC trig echo)` | Distance in cm |
| `(DHT-READ pin type)` | DHT sensor |

### Peripherals

| Form | Description |
|------|-------------|
| `(SERVO pin angle)` | Set servo angle |
| `(I2C-WRITE addr reg val)` | I2C write |
| `(I2C-READ addr reg)` | I2C read |
| `(LCD-INIT rs en d4 d5 d6 d7)` | Init LCD |
| `(LCD-CLEAR)` | Clear LCD |
| `(LCD-PRINT row col text)` | Print to LCD |
| `(NEO-SET pin r g b)` | Set NeoPixel color |
| `(NEO-SHOW pin)` | Flush NeoPixels |
| `(PID-INIT id out in kp ki kd)` | Init PID controller |
| `(CLOSED-LOOP id setpoint)` | Engage PID |
| `(OPEN-LOOP id manual)` | Manual PID output |

### System

| Form | Description |
|------|-------------|
| `(DO stmts...)` | Block / sequence |
| `(INCLUDE "file")` | Include another file |
| `(STRUCT name fields...)` | Define data structure |
| `(NEW struct args...)` | Instantiate struct |
| `(AUTOPILOT-BEGIN/END)` | Record to hardware memory |
| `(BATCH-BEGIN/END)` | Batch operations |
| `(ON-EVENT pin edge "handler")` | Hardware interrupt |
| `(ON-CHANGE pin threshold "handler")` | Analog change detect |
| `(EXIT)` | Halt program |

## Requirements

- **HIL-OS CLI** (`hil-cli`) — for running and building
- **Arduino IDE + TinyGo** — for real hardware compilation
- **CRUMB Circuit Simulator** — for visual simulation
- **VS Code + HIL extension** — for syntax highlighting and snippets

## License

These examples are part of the HIL-OS project by Sherif Rashwan.
