Skip to main content
Homescript uses Lua as its scripting language, providing a simple yet powerful way to automate tasks in your smart home. This guide will walk you through the basics of writing scripts, organizing them, and using built-in functions and libraries.

​
Script Structure

Homescript scripts are organized in a clear directory structure. Each script is a Lua file that defines functions and logic to control devices or respond to events. The main directories include:
  • events/device: Scripts that respond to device events.
  • events/time: Scripts that run at specific times.
  • lib: Helpers, your custom libraries and modules.

​
Writing Your First Script

Let’s create a simple script that turns on a light when motion is detected. Here we assume you have a motion sensor and a smart bulb.
  1. Create a new file in the events/device/motion_sensor/detect directory, e.g., handler.lua.
if event.state == "ON" then
    -- Turn on the light
    device.set("smart_bulb", { state = "ON" })
end
  1. Save the file. Homescript will automatically load and execute this script when the motion sensor detects motion.

​
Using Built-in Functions

Homescript provides several built-in functions to interact with devices and manage state:

​
Device Management

-- Get current device state
local state = device.get("device_id")
-- Returns: {state = "ON", brightness = 200, ...}

-- Set device attributes
device.set("device_id", {state = "ON", brightness = 200})

-- Call device action
device.call("device_id", "toggle", {})

​
Persistent Storage

-- Get persistent state
local value = state.get("my.key")

-- Set persistent state
state.set("my.key", {value = 123, timestamp = os.time()})

-- Delete state
state.delete("my.key")

​
Logging

-- Log information
log.info("This is an info message")
log.warn("This is a warning message")
log.error("This is an error message")

​
Event Object

When a script is triggered by an event, it receives an event object containing relevant information: 
-- Event information
event.source    -- "device", "mqtt", "time", "state", "action"
event.type      -- event type ("state_change", "message", etc.)
event.device    -- device ID (if applicable)
event.attribute -- attribute name (if applicable)
event.topic     -- MQTT topic (if applicable)
event.data      -- event payload (Lua table)

​
Actions

Actions allow you to define custom operations that can be invoked on devices. You can create complex actions to avoid repeating code. 
-- Define an action handler in events/device/smart_bulb/actions/turn_on.lua
if event.data.color then
    device.set(event.device, {state = "ON", color = event.data.color})
else
    device.set(event.device, {state = "ON"})
end

​
Sample Scripts

​
Auto Light Off

Turns off a light after 5 minutes of being on. 
local new_state = event.data.state

if new_state == "ON" then
    log.info("Porch light turned ON, will auto-off in 5 minutes")

    -- Save turn-on time
    state.set("porch.last_on", os.time())

    timer.after(300,  "porch_auto_off", function()
        local last_on = state.get("porch.last_on")
        if last_on and os.time() - last_on >= 300 then
            device.set("porch", {state = "OFF"})
            log.info("Porch light auto-turned OFF after 5 minutes")
        else
            log.info("Porch light was turned ON again, skipping auto-off")
        end
    end)
end

​
Sync Two Lights

Keeps two lights in sync based on one another’s state. 
local new_state = event.data.state

log.info(string.format("Living room lamp: %s", new_state))

-- Sync with bedroom lamp
if new_state == "ON" then
    device.set("bedroom_lamp", {state = "ON"})
else
    device.set("bedroom_lamp", {state = "OFF"})
end