HarixOS: A Linux-Style Real Operating System for ESP8266

HarixOS – A Linux-Style CLI Operating System for ESP8266

HarixOS is a real, CLI-based open source operating system designed specifically for microcontrollers, starting with the ESP8266 family. Unlike typical firmware projects or simple IoT scripts, HarixOS introduces a structured operating system experience on constrained hardware—complete with a shell, filesystem, scripting engine, and safe hardware API layer.

This project transforms the ESP8266 from a basic WiFi module into a fully interactive embedded computer accessible through a serial terminal.

🚀 The Story Behind HarixOS

Most ESP8266 projects follow a simple pattern: connect sensors, blink LEDs, send data to the cloud. But as projects grow, managing logic becomes messy, unsafe, and unscalable.

HarixOS was built to solve this problem.

Instead of writing scattered firmware logic, HarixOS introduces a central operating system layer where everything is controlled through commands—just like Linux systems, but designed for microcontrollers.

The goal was simple:

“What if ESP8266 could feel like a real computer, not just a WiFi chip?”

“What if ESP8266 could feel like a real computer, not just a WiFi chip?”

That idea evolved into HarixOS—a modular OS with a command-line shell, safe API architecture, and a script engine for automation.

🖥️ Screenshots

An Much more Amazing Commands

🧠 Key Philosophy

HarixOS is built around three core principles:

• Simplicity through CLI – Everything is accessible via commands
• Safety by design – Apps never touch hardware directly
• Extensibility first – New boards and features can be added easily

⚙️ Core Features

• 🖥️ Interactive CLI shell (HarixOS>)
• 📁 Linux-like filesystem (LittleFS support)
• ⚡ GPIO control via safe API layer
• 🌐 WiFi management (scan, connect, status)
• 📜.hx scripting engine for automation
• 🧠 Background task scheduler
• 📡 HTTP file downloader (pull command)
• 🧮 Built-in calculator
• 🧾 Notepad CLI editor
• 🔧 System tools (info, heap, reboot, adc)
• 📡 HTTP server for file sharing
• 🧩 Modular API architecture (GPIO, WiFi, FS, System)

🏗️ Architecture Overview

CLI / .hx Scripts
        ↓
HarixOS API Layer (Safe & Structured)
        ↓
ESP8266 Hardware (GPIO, WiFi, ADC, FS)
CLI / .hx Scripts
        ↓
HarixOS API Layer (Safe & Structured)
        ↓
ESP8266 Hardware (GPIO, WiFi, ADC, FS)

This design ensures:

• No unsafe direct hardware access
• Controlled system behavior
• Stable execution even under heavy scripting

📜 Script Engine (.hx)

HarixOS includes a lightweight scripting system for automation:

gpio 2 mode output
gpio 2 on
delay 500
gpio 2 off
delay 500
gpio 2 mode output
gpio 2 on
delay 500
gpio 2 off
delay 500

Scripts can be used for:

• Automation tasks
• Device testing
• Custom mini-apps
• Startup sequences

Getting Started with HarixOS

Prerequisites

• ESP8266 Flasher Tool if using precompiled
• PlatformIO if you use build at your own (installed in VS Code or via pip)
• USB-to-serial adapter or development board for ESP8266
• Any ESP8266-family board (ESP-01, ESP-12E, NodeMCU, D1 mini, etc.)

Precompiled Binaries

If you don’t want to build HarixOS manually, you can use precompiled firmware files.

Download binaries

Prebuilt Latest .bin files are available on the release page.

Example (ESP8266 NodeMCU):

directly flash binary:

esptool.py --port COM3 write_flash 0x00000 firmware.bin

or use any ESP8266 Flasher

Flash addresses (ESP8266)

• 0x00000 → firmware.bin

⚠️ Make sure the binary matches your board (esp01 / nodemcu / d1 mini/ Generic ESP8266).

⚠️ Make sure the binary matches your board (esp01 / nodemcu / d1 mini/ Generic ESP8266).

Serial console (Putty is recommended)

• Start the monitor at 115200 baud:

If You Want To Build and flash On Your Own

• Open the project in VS Code with the PlatformIO extension (or use the CLI).
• Build:

pio run

• Upload (ensure correct COM port; some boards may need boot/program mode wiring):

pio run --target upload

Board environments

• esp01_1m (default)
• esp8266_generic
• nodemcuv2
• d1_mini

Example (NodeMCU):

pio run -e nodemcuv2 --target upload

Serial console

• Start the monitor at 115200 baud:

Putty Is Recommended

• You should see the HarixOS banner (unless settings disables it). Use HarixOS> prompt.

Common commands

• help — list available commands
• info — system and Wi-Fi summary
• pwd / ls — check filesystem
• notepad /myfile.txt — try editing and saving a text file
• gpio list — show available GPIO pins
• wifi scan — scan nearby networks
• run /scripts/myapp.hx — execute a.hx script

See Full Commands Documentation: View Here

.hx Scripts (Automation & External Apps)

HarixOS supports .hx script files for automation and external app development. Scripts use a simple line-based API:

# Create a blink script
notepad /scripts/blink.hx

# Add these lines:
gpio 2 mode output
gpio 2 on
delay 500
gpio 2 off
delay 500

# Save and run:
# HarixOS> run /scripts/blink.hx

Common script commands:

• gpio <pin> on|off|read|toggle — control GPIO
• delay <ms> — wait (milliseconds)
• wifi scan|connect <ssid> <pass>|status — WiFi control
• system info|reboot — system commands

See API Documentation for complete scripting reference.

Using the API Layer

HarixOS provides a structured API layer for building safe applications. Apps never access hardware directly—they always go through the API:

For CLI developers: Commands use the API internally.

For external app developers: Create.hx scripts or C++ apps that call API functions like:

#include "api/gpio_api.h"
harixos::api::GpioAPI::write(2, HIGH);

This design ensures:

• ✅ Apps can't crash the system
• ✅ Boot-critical pins are protected
• ✅ All hardware access is logged and validated

See API Documentation for complete reference.

Notes about hardware

• Usable GPIO pins differ by board. HarixOS blocks ESP8266 flash pins (GPIO6-11) and serial pins (GPIO1/3) by default for safety.
• Boot pins (GPIO0/GPIO2/GPIO15) should not be forced to invalid levels during reset.
• adc reports raw A0 input; available range and scaling depend on your board.

Upgrading

• Make changes and re-run pio run --target upload.
• Files on LittleFS persist across uploads only if flashing does not erase the filesystem; use fs format to reset storage.

🌐 Project Links

🔗 GitHub Repository:https://github.com/Haris16-code/HarixOS

💬 HarixOS Community:https://harixos.harislab.tech

Useful Links:

API & Apps:

• API Reference: Documentation/API.md — Building apps with HarixOS API
• Advanced Applications: Documentation/Advanced-Apps.md — Complex app development guide
• API Robustness: Documentation/API-Robustness.md — Safety and error handling
• Development Roadmap: Documentation/ROADMAP.md — Future features and planned enhancements

User Guides:

• Getting Started: Documentation/Getting-Started.md
• Commands Reference: Documentation/Commands.md
• Script Reference: SCRIPT-REFERENCE.md — Quick.hx command reference
• Filesystem Guide: Documentation/Filesystem.md
• Notepad Guide: Documentation/Notepad.md
• Apps Guide: Documentation/Apps.md
• Troubleshooting: Documentation/Troubleshooting.md

📍 Future Vision

HarixOS is actively evolving with plans for:

• ESP32 support
• Plugin system for apps
• OTA updates
• GUI layer (optional future module)
• Multi-device networking

🤝 Community & Contribution

HarixOS is open-source and community-driven. Contributions are welcome for:

• New commands
• Hardware drivers
• Script engine improvements
• Board support expansion

Join the discussion and build the future of embedded OS systems together.If You Like HarixOS Leave A Star At Github Repository: https://github.com/Haris16-code/HarixOS

Support HarixOS Here