Language Reference

Syntax

HIL uses S-expression syntax. Every expression is wrapped in parentheses:

Syntax
(operator arg1 arg2 ...)

Comments start with ;. Everything after ; on a line is ignored.

Comments
; This is a comment
(LOG "Hello") ; Inline comment

Strings are wrapped in double quotes. Numbers are bare. Hex literals use 0x prefix. Pin names use Arduino notation: A0-A7, D0-D13.

Variables

Operator	Syntax	Description
`SET`	`(SET name value)`	Assign a value to a variable

Examples
(SET led_pin 13)
(SET temp 25.5)
(SET name "sensor1")
(SET addr 0x68)
(SET sum (+ x y))

Data Types

Type	Example	Description
Integer	`42`	Whole numbers
Float	`3.14`	Floating point
Hex	`0x68`	Hexadecimal literal
String	`"hello"`	Text strings
Pin	`D13`, `A0`	Arduino pin references

Arithmetic Operators

Operator	Syntax	Description
`+`	`(+ a b)`	Addition
`-`	`(- a b)`	Subtraction
`*`	`(* a b)`	Multiplication
`/`	`(/ a b)`	Division (returns 0 if divisor is 0)
`%`	`(% a b)`	Modulo (remainder)

Examples
(+ 17 5)       ; => 22
(- 17 5)       ; => 12
(* 17 5)       ; => 85
(/ 17 5)       ; => 3
(% 17 5)       ; => 2
(/ 10 0)       ; => 0 (safe, no crash)

Comparison Operators

Operator	Syntax	Returns 1 if...
`==`	`(== a b)`	a equals b
`!=`	`(!= a b)`	a does not equal b
`>`	`(> a b)`	a is greater than b
`<`	`(< a b)`	a is less than b
`>=`	`(>= a b)`	a is greater than or equal to b
`<=`	`(<= a b)`	a is less than or equal to b

Boolean Logic

Operator	Syntax	Description
`AND`	`(AND a b)`	Returns 1 if both a and b are truthy (non-zero)
`OR`	`(OR a b)`	Returns 1 if either a or b is truthy
`NOT`	`(NOT a)`	Returns 1 if a is falsy (0), 0 if truthy

Truth Tables
(AND 1 1)  ; => 1    (AND 1 0)  ; => 0    (AND 0 0)  ; => 0
(OR 1 1)   ; => 1    (OR 1 0)   ; => 1    (OR 0 0)   ; => 0
(NOT 0)    ; => 1    (NOT 1)    ; => 0    (NOT 42)   ; => 0

; Compound conditions
(AND (> temp 20) (< temp 30))   ; temp between 20 and 30
(OR (== state 1) (== state 2))  ; state is 1 or 2
(NOT (== led 0))                ; led is not 0

Math Utilities

Operator	Syntax	Description
`MIN`	`(MIN a b)`	Returns the smaller of a and b
`MAX`	`(MAX a b)`	Returns the larger of a and b
`ABS`	`(ABS x)`	Returns absolute value of x
`MAP`	`(MAP val inMin inMax outMin outMax)`	Remap value from one range to another
`CONSTRAIN`	`(CONSTRAIN val min max)`	Clamp value to range
`RANDOM`	`(RANDOM min max)`	Random integer in range [min, max]

Examples
(MIN 15 42)                     ; => 15
(MAX 15 42)                     ; => 42
(ABS -42)                       ; => 42
(MAP 512 0 1023 0 255)         ; => 125 (ADC to PWM)
(CONSTRAIN 500 0 255)          ; => 255
(RANDOM 1 6)                    ; => 1-6 (dice roll)

Conditionals

IF

Syntax	Description
`(IF cond then)`	Execute `then` if cond is truthy
`(IF cond then else)`	Execute `then` if truthy, `else` if falsy

IF can also be used as an expression that returns a value:

IF Examples
(IF (> temp 30) (LOG "Hot!") (LOG "Cool"))

; As expression
(SET status (IF (> temp 25) 1 0))

COND

Multi-branch conditional. First matching clause wins. Use 1 as a catch-all default.

COND Syntax
(COND
  ((== command 1) (LOG "START"))
  ((== command 2) (LOG "STOP"))
  (1 (LOG "UNKNOWN"))
)

Loops

WHILE

WHILE Syntax
(WHILE condition
  body
)

FOR

Counter-based loop. Variable runs from from up to (but not including) to.

FOR Syntax
(FOR i 0 10      ; i goes 0, 1, 2, ... 9
  body
)

DO

Group multiple expressions in a block:

DO Syntax
(DO
  (expr1)
  (expr2)
  (expr3)
)

Loop Control

Operator	Description
`BREAK`	Exit the innermost loop immediately
`CONTINUE`	Skip to the next iteration of the innermost loop

Note: BREAK and CONTINUE only affect the innermost enclosing loop. Nested loops are independent.

DEFUN – Define Functions

Create reusable functions with parameters:

Syntax
(DEFUN function-name (param1 param2 ...)
  body
)

Examples
(DEFUN BLINK (pin count delay_ms)
  (WHILE (> count 0)
    (DO
      (WRITE D pin 1) (DELAY delay_ms)
      (WRITE D pin 0) (DELAY delay_ms)
      (SET count (- count 1))
    )
  )
)

(BLINK 13 5 200)  ; Blink pin 13, 5 times, 200ms each

(DEFUN CELSIUS_TO_FAH (c)
  (+ (/ (* c 9) 5) 32)
)

(SET f (CELSIUS_TO_FAH 25))  ; => 77

Note: Function names are automatically uppercased. my-func becomes MY_FUNC.

Recursion

Functions can call themselves. Useful for mathematical algorithms:

Examples
(DEFUN FACTORIAL (n)
  (IF (<= n 1) 1 (* n (FACTORIAL (- n 1))))
)

(DEFUN FIB (n)
  (IF (<= n 2) n (+ (FIB (- n 1)) (FIB (- n 2))))
)

(FACTORIAL 5)  ; => 120
(FIB 10)        ; => 55

Digital I/O

Operator	Syntax	Description
`WRITE`	`(WRITE D pin value)`	Write HIGH (1) or LOW (0) to digital pin
`READ`	`(READ D pin)`	Read digital pin state (returns 0 or 1)
`PIN-MODE`	`(PIN-MODE pin mode)`	Set pin mode: 0=INPUT, 1=OUTPUT, 2=INPUT_PULLUP

Examples
(WRITE D 13 1)     ; LED ON
(WRITE D 13 0)     ; LED OFF
(READ D 2)         ; Read button on pin 2
(PIN-MODE 13 1)    ; Set pin 13 as OUTPUT

Analog I/O

Operator	Syntax	Description
`READ`	`(READ A pin)`	Read analog pin (returns 0-1023)

Examples
(SET val (READ A 0))    ; Read A0
(SET val (READ A 3))    ; Read A3

PWM Output

Operator	Syntax	Description
`WRITE`	`(WRITE P pin value)`	Write PWM value (0-255) to pin

Examples
(WRITE P 9 128)    ; 50% duty cycle on pin 9
(WRITE P 9 255)    ; Full brightness
(WRITE P 9 0)      ; Off

Tone / Sound

Operator	Syntax	Description
`TONE`	`(TONE pin freq duration)`	Play a tone at freq Hz for duration ms

Examples
(TONE 11 440 500)     ; Play A4 for 500ms
(TONE 11 262 200)     ; Play C4 for 200ms
(TONE 11 1000 100)    ; Beep at 1kHz for 100ms

Sensors

Operator	Syntax	Description
`LM35`	`(LM35 pin)`	Read LM35 temperature sensor (returns °C)
`ULTRASONIC`	`(ULTRASONIC trig echo)`	Read HC-SR04 distance (returns cm)
`DHT-READ`	`(DHT-READ pin type)`	Read DHT sensor (type: 11 or 22)

Displays

Operator	Syntax	Description
`LCD-INIT`	`(LCD-INIT rs en d4 d5 d6 d7)`	Initialize 16x2 LCD (4-bit mode)
`LCD-CLEAR`	`(LCD-CLEAR)`	Clear LCD screen
`LCD-PRINT`	`(LCD-PRINT row col text)`	Print text at position

Communication

Operator	Syntax	Description
`I2C-WRITE`	`(I2C-WRITE addr reg val)`	Write to I2C device
`I2C-READ`	`(I2C-READ addr reg)`	Read from I2C device
`SD-WRITE`	`(SD-WRITE cs data)`	Write data to SD card
`RTC-READ`	`(RTC-READ)`	Read RTC timestamp

Actuators

Operator	Syntax	Description
`SERVO`	`(SERVO pin angle)`	Set servo angle (0-180°)
`NEO-SET`	`(NEO-SET pin r g b)`	Set NeoPixel color
`NEO-SHOW`	`(NEO-SHOW pin)`	Update NeoPixel strip

Timing

Operator	Syntax	Description
`DELAY`	`(DELAY ms)`	Pause execution for ms milliseconds
`MILLIS`	`(MILLIS)`	Returns elapsed milliseconds since boot
`DLY-US`	`(DLY-US us)`	Pause for microseconds

Events & Interrupts

Operator	Syntax	Description
`ON-EVENT`	`(ON-EVENT pin mode handler)`	Attach interrupt to pin
`ON-CHANGE`	`(ON-CHANGE A pin threshold handler)`	Trigger on analog change
`EXIT`	`(EXIT)`	Stop program execution

PID Control

Operator	Syntax	Description
`PID-INIT`	`(PID-INIT ch outPin inPin Kp Ki Kd)`	Initialize PID controller
`CLOSED-LOOP`	`(CLOSED-LOOP ch setpoint)`	Engage closed-loop control
`OPEN-LOOP`	`(OPEN-LOOP ch output)`	Disengage PID, set manual output