plua

PLua - Lua Runtime with Fibaro Home Automation Support

PLua is a powerful Lua interpreter built on Python that provides native Fibaro Home Center 3 (HC3) QuickApp development and emulation. Whether you're developing QuickApps for Fibaro home automation or just need a robust Lua runtime with async capabilities, PLua has you covered.

🏠 Why PLua for Fibaro Development?

• 🚀 QuickApp Development: Full Fibaro SDK emulation with real QuickApp lifecycle
• 🖥️ Desktop UI: Native desktop windows for QuickApp interfaces
• 🔄 Live Development: Hot reload, debugging, and instant testing
• 📡 Real-time APIs: HTTP, WebSocket, TCP, UDP, and MQTT support
• 🎯 VS Code Integration: Full debugging, tasks, and deployment tools
• ⚡ Fast Iteration: No need to upload to HC3 for every test

🛠️ Installation

Prerequisites

• Python 3.8+
• macOS, Linux, or Windows

Quick Install (Recommended)

# Install PLua via pip
pip install plua

# Verify installation
plua --version

Development Setup

If you want to contribute or work with the latest development version:

# Clone and set up for development
git clone https://github.com/jangabrielsson/plua.git
cd plua
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

🚀 Quick Start

1. Create a New QuickApp Project

# Initialize a new QuickApp project with scaffolding
plua --init-qa

# Choose from 42 device templates:
# [1] Basic QuickApp - Simple starter template
# [2] Binary Switch - On/Off switch with actions  
# [3] Multilevel Switch - Dimmer/level control
# [4] Temperature Sensor - Temperature measurement
# ... and many more!

This creates a complete project structure:

my-quickapp/
├── .vscode/
│   ├── launch.json    # F5 debugging configuration
│   └── tasks.json     # HC3 upload/sync tasks
├── .project           # HC3 deployment config
└── main.lua          # Your QuickApp code

2. Develop and Test Locally

# Run your QuickApp with full Fibaro SDK
plua --fibaro main.lua

# With desktop UI window (if your QA has --%%desktop:true)
plua --fibaro main.lua

# Run for specific duration
plua --fibaro main.lua --run-for 30  # 30 seconds minimum

3. VS Code Integration

# Open project in VS Code
code .

# Press F5 to run/debug your QuickApp
# Use Ctrl+Shift+P -> "Tasks: Run Task" for HC3 operations:
# - "QA, upload current file as QA to HC3"
# - "QA, update QA (defined in .project)"
# - "QA, update single file (part of .project)"

📱 QuickApp Development

Basic QuickApp Structure

--%%name:My Temperature Sensor
--%%type:com.fibaro.temperatureSensor  
--%%u:{label="temp", text="--°C"}

function QuickApp:onInit()
    self:debug("Temperature sensor started")
    self:updateView("temp", "text", "22.5°C")
    
    -- Simulate temperature readings
    fibaro.setInterval(5000, function()
        local temp = math.random(180, 250) / 10  -- 18.0-25.0°C
        self:updateView("temp", "text", temp .. "°C")
        self:updateProperty("value", temp)
    end)
end

UI Elements

PLua supports all standard Fibaro UI elements:

--%%u:{button="btn1", text="Turn On", onReleased="turnOn"}
--%%u:{slider="level", min="0", max="100", onChanged="setLevel"}  
--%%u:{switch="toggle", text="Auto Mode", onToggled="setAuto"}
--%%u:{label="status", text="Ready"}

Desktop Windows

Add --%%desktop:true to automatically open desktop UI windows:

--%%name:My Smart Light
--%%desktop:true
--%%u:{button="on", text="ON", onReleased="turnOn"}

🎛️ Interactive Development

REPL (Read-Eval-Print Loop)

# Start interactive Lua session (recommended)
plua -i

# With Fibaro SDK loaded
plua -i --fibaro

In the REPL:

> print("Hello from PLua!")
Hello from PLua!

> fibaro.debug("Testing Fibaro API")
[DEBUG] Testing Fibaro API

> local qa = fibaro.createQuickApp(555)
> qa:debug("QuickApp created!")

Telnet Server (for remote access)

PLua includes a multi-session telnet server for remote development:

# Start with telnet server (port 8023)
plua --telnet script.lua

# Or start just the telnet server
plua --telnet

# Connect from another terminal
telnet localhost 8023

🌐 Network & API Support

PLua provides comprehensive networking capabilities:

-- HTTP requests (async)
http.request("https://api.example.com/data", {
    method = "GET",
    success = function(response)
        print("Response:", response.data)
    end
})

-- WebSocket connections
local ws = websocket.connect("ws://localhost:8080")
ws:send("Hello WebSocket!")

-- MQTT client
local mqtt = require("mqtt")
mqtt.connect("broker.hivemq.com", 1883)

-- TCP/UDP sockets
local tcp = require("tcp")
local client = tcp.connect("127.0.0.1", 8080)

🔧 Command Line Options

plua [script.lua] [options]

Positional Arguments:
  script              Lua script file to run (optional)

Options:
  -h, --help          Show help message and exit
  -v, --version       Show version information
  --init-qa           Initialize a new QuickApp project
  -e, --eval EVAL     Execute Lua code fragments
  -i, --interactive   Start interactive Lua REPL (stdin/stdout with prompt_toolkit)
  --telnet            Start telnet server for remote REPL access
  --loglevel LEVEL    Set logging level (debug, info, warning, error)
  -o, --offline       Run in offline mode (disable HC3 connections)
  --desktop [BOOL]    Override desktop UI mode for QuickApp windows (true/false)
  -t, --tool          Run tool, [help, downloadQA, uploadQA, updateFile, updateQA]
  --nodebugger        Disable Lua debugger support
  --fibaro            Enable Fibaro HC3 emulation mode
  -l                  Ignored, for Lua CLI compatibility
  --header HEADER     Add header string (can be used multiple times)
  -a, --args ARGS     Add argument string to pass to the script
  --api-port PORT     Port for FastAPI server (default: 8080)
  --api-host HOST     Host for FastAPI server (default: localhost)
  --telnet-port PORT  Port for telnet server (default: 8023)
  --no-api            Disable FastAPI server
  --run-for N         Run script for specified seconds then terminate:
                      N > 0: Run at least N seconds or until no callbacks
                      N = 0: Run indefinitely (until killed)
                      N < 0: Run exactly |N| seconds

📂 Project Examples

Check out the examples/ directory:

# Fibaro QuickApp examples
ls examples/fibaro/

# Basic Lua examples  
ls examples/lua/

# Python integration examples
ls examples/python/

🔍 Debugging & Development

VS Code Debugging

• Set breakpoints in your Lua code
• Press F5 to start debugging
• Use watch variables, call stack, and step through code

Logging and Debug Output

-- Different log levels
self:debug("Debug message")
self:trace("Trace message") 
fibaro.debug("Global debug")
print("Console output")

Live UI Updates

-- Update UI elements in real-time
self:updateView("label1", "text", "New text")
self:updateView("slider1", "value", 75)

-- Updates immediately appear in desktop windows

🏗️ Advanced Features

Multiple QuickApps

Run several QuickApps simultaneously:

plua --fibaro qa1.lua qa2.lua qa3.lua

Custom Device Types

PLua supports all Fibaro device types and interfaces:

• Binary switches, multilevel switches
• Sensors (temperature, humidity, motion, etc.)
• HVAC systems and thermostats
• Security devices and detectors
• Media players and controllers

📚 Documentation

• docs/QuickApp.md - QuickApp coding quickstart
• docs/VSCode.md - VSCode setup
• docs/Zerobrane.md - Zerobrane setup
• ARCHITECTURE.md - Technical architecture and internals
• QuickApp internals - Some QuickApp implementation deep dives
• docs/ - Detailed documentation and guides
• examples/ - Code examples and templates
• CHANGELOG.md - Release notes and version history

🤝 Contributing

• Fork the repository
• Create a feature branch
• Add tests for new functionality
• Ensure all tests pass
• Submit a pull request

📄 License

MIT License - see LICENSE for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/ directory

Happy QuickApp Development! 🏠✨