{"id":45962163,"url":"https://github.com/jangabrielsson/plua","last_synced_at":"2026-04-26T10:01:21.391Z","repository":{"id":301112481,"uuid":"1008074857","full_name":"jangabrielsson/plua","owner":"jangabrielsson","description":"Lua interpreter and Fibaro HC3 development environment","archived":false,"fork":false,"pushed_at":"2026-04-22T09:23:44.000Z","size":4821,"stargazers_count":6,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-22T11:29:53.780Z","etag":null,"topics":["fibaro","hc3","lua","quickapp"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jangabrielsson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-25T01:50:08.000Z","updated_at":"2026-04-22T09:23:47.000Z","dependencies_parsed_at":"2025-07-09T21:34:53.318Z","dependency_job_id":"e2665c8a-66c0-45b8-9aea-ea5f1a30c201","html_url":"https://github.com/jangabrielsson/plua","commit_stats":null,"previous_names":["jangabrielsson/plua"],"tags_count":139,"template":false,"template_full_name":null,"purl":"pkg:github/jangabrielsson/plua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangabrielsson%2Fplua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangabrielsson%2Fplua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangabrielsson%2Fplua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangabrielsson%2Fplua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jangabrielsson","download_url":"https://codeload.github.com/jangabrielsson/plua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangabrielsson%2Fplua/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32292958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fibaro","hc3","lua","quickapp"],"created_at":"2026-02-28T13:55:41.106Z","updated_at":"2026-04-26T10:01:21.377Z","avatar_url":"https://github.com/jangabrielsson.png","language":"Lua","funding_links":["https://www.buymeacoffee.com/rywnwpdvvni"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/jangabrielsson/plua/main/docs/Plua.png\" alt=\"PLua Logo\" width=\"320\"/\u003e\n\u003c/p\u003e\n\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003ca href=\"https://www.buymeacoffee.com/rywnwpdvvni\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"\u003e\u003c/a\u003e\n\n# PLua - Lua Runtime with Fibaro Home Automation Support\n\nPLua 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.\n\n## 🏠 Why PLua for Fibaro Development?\n\n- **🚀 QuickApp Development**: Full Fibaro SDK emulation with real QuickApp lifecycle\n- **🖥️ Desktop UI**: Native desktop windows for QuickApp interfaces  \n- **🔄 Live Development**: Hot reload, debugging, and instant testing\n- **📡 Real-time APIs**: HTTP, WebSocket, TCP, UDP, and MQTT support\n- **🎯 VS Code Integration**: Full debugging, tasks, and deployment tools\n- **⚡ Fast Iteration**: No need to upload to HC3 for every test\n\n## 🛠️ Installation\n\n### Prerequisites\n- Python 3.8+ \n- macOS, Linux, or Windows\n\n### Quick Install (Recommended)\n```bash\n# Install PLua via pip\npip install plua\n\n# Verify installation\nplua --version\n```\n\n### Development Setup\nIf you want to contribute or work with the latest development version:\n```bash\n# Clone and set up for development\ngit clone https://github.com/jangabrielsson/plua.git\ncd plua\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install -e .\n```\n\n## � HC3 Credentials Setup\n\nTo connect PLua to your Fibaro Home Center 3, you need to provide credentials. PLua reads them from environment variables, which you can set in a `.env` file.\n\n### Option 1: Project `.env` file (recommended)\nCreate a `.env` file in your project directory:\n```ini\nHC3_URL=http://192.168.1.100\nHC3_USER=admin\nHC3_PASSWORD=your-password\nHC3_PIN=1234\n```\n\u003e `HC3_PIN` is only required for restricted API calls (e.g., accessing alarm panels).\n\n### Option 2: Global `~/.env` file\nPlace a `.env` file in your home directory (`~/.env`) to share credentials across all projects — useful if you work with a single HC3. The format is the same as above.\n\n### Option 3: Shell environment variables\n```bash\nexport HC3_URL=http://192.168.1.100\nexport HC3_USER=admin\nexport HC3_PASSWORD=your-password\nexport HC3_PIN=1234\n```\n\n### Lookup order\nPLua checks in this order and uses the first match found:\n1. System environment variables\n2. `.env` in the current working directory\n3. `~/.env` in your home directory\n\n\u003e **Security note**: Add `.env` to your `.gitignore` to avoid committing credentials.\n\n### Test your connection\n```bash\nplua --diagnostic\n```\nThis prints a summary of your PLua installation, HC3 connection status, and basic device/system info from your HC3. If it connects successfully you're ready to go.\n\n---\n\n## �🚀 Quick Start\n\n### 1. Create a New QuickApp Project\n```bash\n# Initialize a new QuickApp project with scaffolding\nplua --init-qa\n\n# Choose from 42 device templates:\n# [1] Basic QuickApp - Simple starter template\n# [2] Binary Switch - On/Off switch with actions  \n# [3] Multilevel Switch - Dimmer/level control\n# [4] Temperature Sensor - Temperature measurement\n# ... and many more!\n```\n\nThis creates a complete project structure:\n```\nmy-quickapp/\n├── .vscode/\n│   ├── launch.json    # F5 debugging configuration\n│   └── tasks.json     # HC3 upload/sync tasks\n├── .project           # HC3 deployment config\n└── main.lua          # Your QuickApp code\n```\n\n### 2. Develop and Test Locally\n```bash\n# Run your QuickApp with full Fibaro SDK\nplua --fibaro main.lua\n\n# With desktop UI window (if your QA has --%%desktop:true)\nplua --fibaro main.lua\n\n# Run for specific duration\nplua --fibaro main.lua --run-for 30  # 30 seconds minimum\n```\n\n### 3. VS Code Integration\n```bash\n# Open project in VS Code\ncode .\n\n# Press F5 to run/debug your QuickApp\n# Use Ctrl+Shift+P -\u003e \"Tasks: Run Task\" for HC3 operations:\n# - \"QA, upload current file as QA to HC3\"\n# - \"QA, update QA (defined in .project)\"\n# - \"QA, update single file (part of .project)\"\n```\n\n## 📱 QuickApp Development\n\n### Basic QuickApp Structure\n```lua\n--%%name:My Temperature Sensor\n--%%type:com.fibaro.temperatureSensor  \n--%%u:{label=\"temp\", text=\"--°C\"}\n\nfunction QuickApp:onInit()\n    self:debug(\"Temperature sensor started\")\n    self:updateView(\"temp\", \"text\", \"22.5°C\")\n    \n    -- Simulate temperature readings\n    fibaro.setInterval(5000, function()\n        local temp = math.random(180, 250) / 10  -- 18.0-25.0°C\n        self:updateView(\"temp\", \"text\", temp .. \"°C\")\n        self:updateProperty(\"value\", temp)\n    end)\nend\n```\n\n### UI Elements\nPLua supports all standard Fibaro UI elements:\n```lua\n--%%u:{button=\"btn1\", text=\"Turn On\", onReleased=\"turnOn\"}\n--%%u:{slider=\"level\", min=\"0\", max=\"100\", onChanged=\"setLevel\"}  \n--%%u:{switch=\"toggle\", text=\"Auto Mode\", onToggled=\"setAuto\"}\n--%%u:{label=\"status\", text=\"Ready\"}\n```\n\n### Desktop Windows\nAdd `--%%desktop:true` to automatically open desktop UI windows:\n```lua\n--%%name:My Smart Light\n--%%desktop:true\n--%%u:{button=\"on\", text=\"ON\", onReleased=\"turnOn\"}\n```\n\n## 🎛️ Interactive Development\n\n### REPL (Read-Eval-Print Loop)\n```bash\n# Start interactive Lua session (recommended)\nplua -i\n\n# With Fibaro SDK loaded\nplua -i --fibaro\n```\n\nIn the REPL:\n```lua\n\u003e print(\"Hello from PLua!\")\nHello from PLua!\n\n\u003e fibaro.debug(\"Testing Fibaro API\")\n[DEBUG] Testing Fibaro API\n\n\u003e local qa = fibaro.createQuickApp(555)\n\u003e qa:debug(\"QuickApp created!\")\n```\n\n### Telnet Server (for remote access)\nPLua includes a multi-session telnet server for remote development:\n```bash\n# Start with telnet server (port 8023)\nplua --telnet script.lua\n\n# Or start just the telnet server\nplua --telnet\n\n# Connect from another terminal\ntelnet localhost 8023\n```\n\n## 🌐 Network \u0026 API Support\n\nPLua provides comprehensive networking capabilities:\n\n```lua\n-- HTTP requests (async)\nhttp.request(\"https://api.example.com/data\", {\n    method = \"GET\",\n    success = function(response)\n        print(\"Response:\", response.data)\n    end\n})\n\n-- WebSocket connections\nlocal ws = websocket.connect(\"ws://localhost:8080\")\nws:send(\"Hello WebSocket!\")\n\n-- MQTT client\nlocal mqtt = require(\"mqtt\")\nmqtt.connect(\"broker.hivemq.com\", 1883)\n\n-- TCP/UDP sockets\nlocal tcp = require(\"tcp\")\nlocal client = tcp.connect(\"127.0.0.1\", 8080)\n```\n\n## 🔧 Command Line Options\n\n```bash\nplua [script.lua] [options]\n\nPositional Arguments:\n  script              Lua script file to run (optional)\n\nOptions:\n  -h, --help          Show help message and exit\n  -v, --version       Show version information\n  --init-qa           Initialize a new QuickApp project\n  -e, --eval EVAL     Execute Lua code fragments\n  -i, --interactive   Start interactive Lua REPL (stdin/stdout with prompt_toolkit)\n  --telnet            Start telnet server for remote REPL access\n  --loglevel LEVEL    Set logging level (debug, info, warning, error)\n  -o, --offline       Run in offline mode (disable HC3 connections)\n  --desktop [BOOL]    Override desktop UI mode for QuickApp windows (true/false)\n  -t, --tool          Run tool, [help, downloadQA, uploadQA, updateFile, updateQA]\n  --nodebugger        Disable Lua debugger support\n  --fibaro            Enable Fibaro HC3 emulation mode\n  -l                  Ignored, for Lua CLI compatibility\n  --header HEADER     Add header string (can be used multiple times)\n  -a, --args ARGS     Add argument string to pass to the script\n  --api-port PORT     Port for FastAPI server (default: 8080)\n  --api-host HOST     Host for FastAPI server (default: 0.0.0.0 - all interfaces)\n  --telnet-port PORT  Port for telnet server (default: 8023)\n  --no-api            Disable FastAPI server\n  --run-for N         Run script for specified seconds then terminate:\n                      N \u003e 0: Run at least N seconds or until no callbacks\n                      N = 0: Run indefinitely (until killed)\n                      N \u003c 0: Run exactly |N| seconds\n```\n\n## 📂 Project Examples\n\nCheck out the `examples/` directory:\n```bash\n# Fibaro QuickApp examples\nls examples/fibaro/\n\n# Basic Lua examples  \nls examples/lua/\n\n# Python integration examples\nls examples/python/\n```\n\n## 🔍 Debugging \u0026 Development\n\n### VS Code Debugging\n1. Set breakpoints in your Lua code\n2. Press F5 to start debugging\n3. Use watch variables, call stack, and step through code\n\n### Logging and Debug Output\n```lua\n-- Different log levels\nself:debug(\"Debug message\")\nself:trace(\"Trace message\") \nfibaro.debug(\"Global debug\")\nprint(\"Console output\")\n```\n\n### Live UI Updates\n```lua\n-- Update UI elements in real-time\nself:updateView(\"label1\", \"text\", \"New text\")\nself:updateView(\"slider1\", \"value\", 75)\n\n-- Updates immediately appear in desktop windows\n```\n\n## 🏗️ Advanced Features\n\n### Multiple QuickApps\nRun several QuickApps simultaneously:\n```bash\nplua --fibaro qa1.lua qa2.lua qa3.lua\n```\n\n### Custom Device Types\nPLua supports all Fibaro device types and interfaces:\n- Binary switches, multilevel switches\n- Sensors (temperature, humidity, motion, etc.)  \n- HVAC systems and thermostats\n- Security devices and detectors\n- Media players and controllers\n\n## 📚 Documentation\n- [docs/QuickApp.md](docs/QuickApp.md) - QuickApp coding quickstart\n- [docs/VSCode.md](docs/VSCode.md) - VSCode setup\n- [docs/Zerobrane.md](docs/Zerobrane.md) - Zerobrane setup\n- [docs/ARCHITECTURE-OVERVIEW.md](docs/ARCHITECTURE-OVERVIEW.md) - **Friendly \"how plua works\" overview for QA developers**\n- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical architecture and internals (deep dive)\n- [QuickApp internals](docs/tutorials/README.md) - Some QuickApp implementation deep dives\n- [docs/](docs/) - Detailed documentation and guides\n- [examples/](examples/) - Code examples and templates\n- [CHANGELOG.md](CHANGELOG.md) - Release notes and version history\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality  \n4. Ensure all tests pass\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🆘 Support\n\n- **Issues**: [GitHub Issues](https://github.com/jangabrielsson/plua/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/jangabrielsson/plua/discussions)\n- **Documentation**: [docs/](docs/) directory\n\n---\n\n**Happy QuickApp Development! 🏠✨**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjangabrielsson%2Fplua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjangabrielsson%2Fplua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjangabrielsson%2Fplua/lists"}