Tutorials – HIL

Tutorial 1: Hello World

Your first HIL program. Takes 2 minutes.

Create a file

Create a file called hello.hil with this content:

hello.hil

(LOG "Hello, World!")
(LOG "My first HIL-OS program.")
(LOG "2 + 2 = " (+ 2 2))

Run it

hil-cli simulate hello.hil

You should see:

Output
Hello, World!
My first HIL-OS program.
2 + 2 = 4

Congratulations! You just ran your first HIL program.

Tutorial 2: Variables and Math

Learn to store data and perform calculations.

math.hil

; Store values in variables
(SET temperature 25)
(SET humidity 60)

; Print them
(LOG "Temperature: " temperature " C")
(LOG "Humidity: " humidity "%")

; Do math
(SET temp_f (+ (/ (* temperature 9) 5) 32))
(LOG "Temperature in Fahrenheit: " temp_f)

; Boolean logic
(IF (AND (> temperature 20) (< temperature 30))
  (LOG "Comfortable temperature!")
  (LOG "Need adjustment.")
)

hil-cli simulate math.hil

Tutorial 3: Loops and Control Flow

Repeat actions and make decisions.

loops.hil

; WHILE loop: countdown
(SET count 5)
(WHILE (> count 0)
  (DO
    (LOG count "...")
    (SET count (- count 1))
  )
)
(LOG "LIFTOFF!")

; FOR loop: count 0 to 4
(LOG "Counting:")
(FOR i 0 5
  (LOG "  i = " i)
)

; Conditional with COND
(SET command 3)
(COND
  ((== command 1) (LOG "Start"))
  ((== command 2) (LOG "Stop"))
  ((== command 3) (LOG "Reverse"))
  (1 (LOG "Unknown"))
)

Tutorial 4: Functions

Write reusable code with DEFUN.

functions.hil

; Define a function that converts Celsius to Fahrenheit
(DEFUN C_TO_F (c)
  (+ (/ (* c 9) 5) 32)
)

; Use it
(LOG "0C = " (C_TO_F 0) "F")
(LOG "100C = " (C_TO_F 100) "F")
(LOG "25C = " (C_TO_F 25) "F")

; Function with multiple parameters
(DEFUN CLAMP (val low high)
  (IF (< val low)
    low
    (IF (> val high) high val)
  )
)

; Test it
(LOG "Clamp 50 to [0,25]: " (CLAMP 50 0 25))
(LOG "Clamp 10 to [0,25]: " (CLAMP 10 0 25))
(LOG "Clamp 15 to [0,25]: " (CLAMP 15 0 25))

Tutorial 5: Blink an LED (Real Hardware)

Run on real Arduino hardware.

Wire it up

Connect an LED + 220Ω resistor to pin 13 on your Arduino.

blink.hil

(SET led 13)
(SET count 10)

(WHILE (> count 0)
  (DO
    (WRITE D led 1)
    (LOG "LED ON")
    (DELAY 500)

    (WRITE D led 0)
    (LOG "LED OFF")
    (DELAY 500)

    (SET count (- count 1))
  )
)

(LOG "Done blinking!")

Connect and run

hil-cli ports

hil-cli run blink.hil -port COM3

Tutorial 6: Read a Sensor

Read analog data and make decisions.

sensor.hil

; LM35 temperature sensor on A0
; LED on D13, Buzzer on D11

(SET sensor 0)
(SET led 13)
(SET buz 11)
(SET alarm_temp 30)

(LOG "Temperature Monitor")
(LOG "Alarm threshold: " alarm_temp "C")

(WHILE 1
  (DO
    ; Read temperature
    (SET temp (LM35 sensor))
    (LOG "Temp: " temp "C")

    ; Map temperature to LED brightness
    (SET brightness (CONSTRAIN (MAP temp 0 50 0 255) 0 255))
    (WRITE P led brightness)

    ; Alarm if too hot
    (IF (>= temp alarm_temp)
      (DO
        (LOG "!! OVERHEAT !!")
        (TONE buz 1000 200)
      )
    )

    (DELAY 1000)
  )
)

Tutorial 7: State Machines

Build complex behavior with COND and states.

traffic-light.hil

; Traffic Light Controller
; Red=D13, Yellow=D12, Green=D11

(SET red 13)
(SET yellow 12)
(SET green 11)
(SET state 0)
(SET timer 0)

; All LEDs off
(WRITE D red 0)
(WRITE D yellow 0)
(WRITE D green 0)

; Run 3 cycles
(SET cycles 0)
(WHILE (< cycles 3)
  (DO
    (COND
      ((== state 0)
        (DO
          (WRITE D green 1) (WRITE D yellow 0) (WRITE D red 0)
          (LOG "GREEN — Go (" timer "s)")
          (IF (>= timer 3) (DO (SET state 1) (SET timer 0)))
          (DELAY 1000) (SET timer (+ timer 1))
        )
      )
      ((== state 1)
        (DO
          (WRITE D green 0) (WRITE D yellow 1) (WRITE D red 0)
          (LOG "YELLOW — Caution (" timer "s)")
          (IF (>= timer 1) (DO (SET state 2) (SET timer 0)))
          (DELAY 1000) (SET timer (+ timer 1))
        )
      )
      ((== state 2)
        (DO
          (WRITE D green 0) (WRITE D yellow 0) (WRITE D red 1)
          (LOG "RED — Stop (" timer "s)")
          (IF (>= timer 3) (DO (SET state 0) (SET timer 0) (SET cycles (+ cycles 1))))
          (DELAY 1000) (SET timer (+ timer 1))
        )
      )
    )
  )
)

(LOG "Done! " cycles " cycles complete.")

Tutorial 8: CRUMB Simulation

Visualize your circuit in the CRUMB simulator.

Generate a CRUMB project

hil-cli crumb examples/08-projects/thermostat.hil --open

This creates a .cru file and opens it in CRUMB.

What CRUMB shows

The CRUMB simulator renders your circuit with all connected components, LEDs, sensors, servos, displays, and runs the transpiled Arduino C code in real-time.

Tip: Install CRUMB from the Microsoft Store or the official website. It's free for personal use.

Next Steps

◇ Language Reference

Complete list of all operators, functions, and syntax.

Open Reference →

◌ 34 Examples

Browse all examples from beginner to advanced.

View Examples →

⚙ CLI Reference

All commands and options for hil-cli.

CLI Docs →

★ Architecture

Understand how HIL works under the hood.

Read Architecture →

Learn HIL step by step