micrOS

A local-first automation platform for Wi-Fi-enabled MicroPython boards.

Build a network-controlled lamp, read a sensor over Socket/HTTP, or let one board trigger another. micrOS turns a compatible Wi-Fi microcontroller into a programmable automation node—without a required cloud service.

Write the hardware behavior in MicroPython; micrOS handles networking, configuration, background jobs, scheduling, interrupts and updates.

micrOS is a network-addressable edge application platform for MicroPython MCUs, built around a dynamically loadable plug-in architecture.

Contents

• 🎬 See it in action
• 🚀 Start using micrOS — installation, Wi-Fi setup, and first commands
• 📦 Applications · micrOS Packages
• 🌐 Network modes · Configuration parameters
• 💬 Tutorials and community
• ⚙️ Advanced use — automation, hardware, configuration, and developer tools
• 🧩 Create a Load Module · Architecture
• 📝 Cheat sheets and maintainer notes

The optional on-device web UI: REST console, configuration, application controls, and file management.

Why micrOS?

• One function, several ways to use it. Public functions in LM_*.py Load Modules are callable from the shell, REST API, schedules, interrupts, and background jobs.
• Local control. Clients connect directly to nodes over Wi-Fi. No cloud account or always-on server is required; time and sunrise/sunset lookups use external services.
• A runtime you can build on. STA/AP networking, NTP/RTC, pin mapping, async tasks, OTA updates, and device-to-device commands are included.
• Load only what you need. Modules are imported on demand and stay resident. Available memory determines how many you can combine.

Who is it for?

For MicroPython developers who want reusable device infrastructure, makers building local automation, hardware experimenters adding sensors or actuators, and developers connecting several nodes over sockets or ESP-NOW.

See it in action

Ring Lamp	RoboArm	RGB + CCT lighting
Generated controls for a 24-pixel NeoPixel lamp.	A Wi-Fi-controlled servo application and laser cat toy.	Full-color and tunable-white LED control from one node.

Start with an existing application, then add your own behavior as a Load Module.

Start using micrOS

You only need three ideas: a node is your board running micrOS; DevToolKit installs and connects to it from your computer; a Load Module is a Python application on the board. You don't need to understand the runtime internals to use an existing application.

Before you begin, have a compatible Wi-Fi MicroPython board, a USB data cable, a computer, and your Wi-Fi credentials ready. Check the firmware catalog for your board; see boards and memory for larger applications.

Follow these four steps to get a node online and make your first request.

Use DevToolKit on macOS, Linux, or Windows to deploy your first node. Start with the GUI; the CLI supports interactive use and automation.

1. Install Python and DevToolKit

Install Python 3.12 or newer and add it to your system path. The original setup used Python 3.12.0.

On macOS, open Terminal with Command+Space, type terminal, and press Enter. On Windows, press Windows+R, type powershell, and press Enter.

On macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install micrOSDevToolKit

Verify the Python installation with python3 --version. Update DevToolKit later with python3 -m pip install --upgrade micrOSDevToolKit.

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install micrOSDevToolKit

Activate the environment again when opening a new terminal. If PowerShell blocks activation, use Command Prompt with .venv\Scripts\activate.bat. On Windows, update with python -m pip install --upgrade micrOSDevToolKit.

Run package installation as a normal user; approve administrator access only for USB-driver installation.

2. Deploy micrOS over USB

Start the graphical toolkit:

devToolKit.py

1. Connect your board over USB.
2. Select the matching board and MicroPython firmware from the available lists.
3. Select Deploy (USB) and confirm the operation.
4. Wait for deployment to complete and the board to restart.

On first deployment, DevToolKit may offer to install the Serial USB driver required by your platform.

Deploy (USB) erases existing firmware and files. Back up a board you already use. The first toolkit launch installs optional GUI, compiler, and media dependencies; keep internet access available until it finishes.

3. Configure Wi-Fi and open the web UI

On first startup, an unconfigured node creates its own Wi-Fi access point when it cannot connect to your network:

1. Connect your computer to the node01 Wi-Fi network using the factory password ADmin123.
2. Start devToolKit.py -s -c and select __device_on_AP__ at 192.168.4.1.
3. Enter these commands one line at a time in the micrOS shell. Replace the angle-bracket placeholders, including the brackets, with your own values. The device password must be 8–9 characters long and contain uppercase and lowercase letters and a digit. Check that each setting succeeds.

conf
staessid <your-wifi-name>
stapwd <your-wifi-password>
devfid MyNode
appwd <new-device-password>
webui True
noconf
reboot

webui True enables the web interface. No boot-hook configuration is needed.

4. Reconnect your computer or phone to the normal local network.
5. Open http://MyNode.local in a browser. If you see 🚀 Load Web Apps, click it to load the dashboard and configuration apps. The page reloads with links to the available apps.

If .local does not resolve, use the node IP shown by discovery or your router: http://<node-ip>. The toolkit's default AP address is 192.168.4.1; another MicroPython port may use a different address. Keep your computer connected to the board's Wi-Fi even if it reports that the network has no internet access.

If you deploy a previously prepared configuration containing valid Wi-Fi credentials, the node can join that network directly and the access-point configuration step is unnecessary. Change the factory device password during initial setup.

4. Confirm the installation

Open http://MyNode.local/rest/system/info to call the first REST endpoint, or connect through DevToolKit and try the shell:

help
system info
system heartbeat

system info reports the board, MicroPython version, memory, filesystem, and uptime. help all lists the installed Load Modules. From there, use the application catalog or create a custom Load Module.

The dashboard displays controls for modules with widget metadata, so a fresh node may have few controls until you load an application. Protected configuration operations may prompt for your device password.

What to try next

Choose a module from the application catalog, check its wiring and help, then try its commands. The shell uses module function; HTTP uses /rest/module/function, as in the system-info example above. Module and hardware availability depend on your deployment.

You now have the basics. Use the network modes and configuration tables below as your everyday reference; continue to Advanced use for custom behavior, automation, different firmware, or multi-node tooling.

Tutorials and community

Questions, ideas, and technical requests are welcome in GitHub Discussions. If micrOS is useful to you, a GitHub star helps other MicroPython and embedded-automation developers find it.

Network modes

A node normally joins the local Wi-Fi network in station mode. It can fall back to its own access point for configuration. Set nwmd, staessid, stapwd, and devip using the configuration reference below. Clients communicate directly with a node; nodes can invoke each other over sockets or ESP-NOW.

Node configuration reference

These parameters control micrOS core functionality and allow an entire system to be assembled from configuration.

Basic parameters:

Advanced parameter options:

Most unset string parameters use n/a. Cron requires Timer(1); the original implementation targets the ESP32 port.

Advanced use

Use this section as a reference, not a second setup checklist. It covers operating and extending your nodes. Runtime design belongs in ARCHITECTURE.md; application APIs and examples belong in MODULE_GUIDE.md.

• Interfaces and applications
• Automation commands
• Boards and memory · Peripherals · Pinouts
• Gateway and monitoring
• Development and customization — modules, firmware images, CLI, and examples
• Documentation
• Roadmap · Release history
• Cheat sheets and maintainer notes

Interfaces and applications

Load Modules are micrOS applications. Use the catalog to find one for your hardware, or follow the development guide to write your own.

• Browse the built-in application and peripheral catalog
• Create a custom Load Module
• Install shared micrOS packages
• Use the micrOS Gateway
• AI integration:

Optional file manager

Enable the file manager for this session with web load fileserver=True in the shell. Use that command in boothook to enable it on subsequent boots, preserving any other startup actions. Protected file operations may prompt for your device password.

Configure automation

Startup and network settings

OTA tooling monitors updates and restarts the node. To configure startup and network behavior, edit node_config.json through the shell or web UI:

• boothook runs initialization before network setup—for example, rgb load; neopixel load restores application pins and state. Prefix an action with # to disable it while experimenting.
• nwmd selects station (STA) or access-point (AP) mode. devip controls the stored/static IP and devfid the hostname (<devfid>.local).
• In STA mode, NTP and UTC handling set the clock, using ip-api.com for location/timezone data. The runtime also tracks uptime.

Schedules and external events

Cron timestamps use WD:H:M:S!module function, with ranges 0–6:0–23:0–59:0–59 and * for any value. Monday is 0 and Sunday is 6; 0-2 selects Monday through Wednesday. Separate entries with ;, but use only one command per entry; comments are not supported.

Instead of a timestamp, use sunrise or sunset with an optional minute offset: sunrise+30 or sunset!rgb rgb r=10 g=60 b=100. Times come from api.sunrise-sunset.org. Timer support depends on the MicroPython port.

Shell and background jobs

ShellCli provides wireless commands such as help, version, reboot, modules, and webrepl. Enter conf to read or change configuration, use dump to show it, and leave with noconf. webrepl --update restarts into WebREPL mode and waits about 20 seconds for an OTA update. For normal boot versus WebREPL recovery mode, see the loader and boot-flow reference.

Use help for shell commands and active modules, or help all to include all installed modules. Older output examples below use the former help lm syntax.

Run Load Module functions in the background:

Example task list (the active services depend on configuration):

TinyDevBoard $ task list
---- micrOS  top ----
#queue: 18 #load: 3%

#Active   #taskID
Yes       server
Yes       idle
Yes       telegram.server_bot
Yes       espnow.server

The host-side socket client supports interactive and non-interactive use. To discover nodes and connect:

./devToolKit.py --search_devices --connect

Hardware and peripherals

Boards and memory

micrOS targets compatible MicroPython boards with Wi-Fi, not one chip family or manufacturer. Included mappings cover multiple Espressif boards as well as RP2/Pico W and provider-specific boards such as TinyPICO, M5Stamp, and QT Py. Deployment method and peripheral availability vary by MicroPython port.

Regardless of provider, enabling more than approximately two Load Modules together with the full Web UI generally requires more than 150–200 KB of available RAM.

For larger applications, choose a board with 2, 4, or 8 MB of additional PSRAM. It may be described as PSRAM, SPIRAM, or octal PSRAM. Check the board specification before buying; the selected MicroPython build must support it.

Examples of higher-memory hardware:

esp32s3: A fast Espressif MCU with PSRAM detection. Typical configurations include 2 MB for general use and 4–8 MB for image processing, audio, and larger combinations of GPIO applications.

esp32s3-octo: Uses an eight-bit PSRAM interface for higher throughput.

tinypico: Excellent compact hardware with 4 MB of PSRAM, at a higher price.

esp32cam: Uses a camera-capable image. The original project notes describe an 8 MB configuration; check the actual board, as that is not a guarantee for every board sold under this name.

The following figures are historical project measurements and estimates, not limits enforced by the runtime. The original guide estimated roughly 250 KB for a fuller setup and recommended 2–8 MB PSRAM configurations:

• A heavily loaded 4 MB system used approximately 230 KB (5.6%), including oled_ui and several other modules.
• Camera streaming can consume approximately 2 MB, or 50% of a 4 MB configuration.

Note:

A standard esp32 can work well with ShellCli and without WebCli. Web assets and multiple asynchronous tasks each consume additional memory. The original guide reported instability near 80% heap use in some setups; allocation sizes and fragmentation matter too, so this is not a universal threshold. A spare ESP32 is still a good way to explore a smaller set of micrOS features.

Built-in peripheral support

#Sensors / inputs #Actuators / outputs

Browse Load Module functions

Device Pinouts for wiring

Logical pin association handling

microIO resolves logical pins through modules/IO_*.py board maps. Use an existing map such as IO_esp32.py as a template for IO_<name>.py, then set cstmpmap to <name>. You can override individual pins too: neop:25 maps the logical NeoPixel pin to GPIO 25. Inspect mappings with system pinmap.

micrOS/source/microIO.py

LogicalPin lookup tables:

• tinypico
• esp32
• esp32s2
• esp32s3
• M5Stamp
• QT Py
• raspberryPicoW - reset needed after ota update (webrepl limitation)
• IO_*.py and other mappings

Use constant variables for pin-map declarations; see the files for examples. These files are also precompiled automatically into .mpy bytecode.

GENERAL CONTROLLER CONCEPT: microPLC

Gateway and monitoring

Use the gateway with Prometheus for metrics and Grafana for dashboards. See the Docker setup guide for the combined stack and dashboard examples.

Resources:

Modify prometheus.yml to select the sensor endpoints from which Prometheus should scrape data.

• docker-compose
• prometheus config

cd ./env/docker
docker-compose -p gateway up -d

Official DockerHub image

Development and customization

Create a Load Module

To add an application, create LM_<your_app_name>.py, write public Python functions, and upload it through DevToolKit's drag-and-drop GUI. For example, system info calls info() in modules/LM_system.py. See the Load Module guide for the API contract.

USB updates and custom images

The selected firmware filename controls which resources are copied from toolkit/workspace/precompiled/:

• A stock MicroPython image keeps the full development deployment.
• A prebuilt micrOS-* image already contains the core and receives only the configured web assets and minimum LM/IO modules.

USB deploy and update display the selected mode. USB update restores node_config.json for both image types. Skip MicroPython keeps the current firmware and copies only the required files.

Build all configured micrOS-* images with:

python3 toolkit/micrOSImageBuilder.py

Supported custom targets are esp32, esp32c3, esp32c6, and esp32s3. The MicroPython image guide contains the binary catalog, custom image list, and image notes. Image settings and release resources are defined in toolkit/micrOSImageConfig.json.

Custom images append a [micrOS] marker to the board description shown by system info. Full OTA reads the hello mode and skips frozen core files on rel devices.

Development branches and legacy deployments

Historical GUI terminology: “Secure Core” (OTA static modules) referred to boot.py, micrOSloader.mpy, Network.mpy, ConfigHandler.mpy, and Debug.mpy. These are legacy names, not the current release-image resource list; see deployment modes.

Alternative branches:

micrOS-Core 3.0 - with minimal set of default Load Modules

micrOS-develop - for experimentation

lightweight-for-esp8266 - really old legacy v1.3

Erase, flash MicroPython, and install micrOS

From the repository directory containing devToolKit.py, run:

devToolKit.py --make

Follow the interactive prompts. This operation erases the board.

Then discover and connect to the device:

devToolKit.py -s -c

User commands

devToolKit.py -h

optional arguments:
  -h, --help            show this help message and exit

Base commands:
  -m, --make            Erase & Deploy & Precompile (micrOS) & Install (micrOS)
  -r, --update          Update/redeploy connected (USB) micrOS
  -s, --search_devices  Search devices on connected wifi network.
  -o, --OTA             OTA (over-the-air update with WebREPL)
  -c, --connect         Connect through the socket client
  -p CONNECT_PARAMETERS, --connect_parameters CONNECT_PARAMETERS
                        Parameters for connection in non-interactive mode.
  -a APPLICATIONS, --applications APPLICATIONS
                        List/Execute frontend applications. [list]
  -stat, --node_status  Show all available micrOS devices status data.
  -cl, --clean          Clean user connection data: device_conn_cache.json
  
  ...

Search devices

devToolKit.py --search_devices

or

devToolKit.py -s

List discovered devices with status updates

devToolKit.py -stat

or

devToolKit.py --node_status

Output:

[ UID ]                 [ FUID ]              [ IP ]          [ STATUS ] [ VERSION ] [ MODE ] [COMM SEC] [WEBUI | ESPNOW | CRON | TIMIRQ] 
__localhost__           __simulator__         127.0.0.1       OFFLINE    <n/a>       n/a      n/a        n/a      n/a      n/a      n/a   
micr24587c53b170OS      Entrance              10.0.1.55       ONLINE     3.5.0-0     rel      0.181      ON       OFF      OFF      OFF   
micr308398c73e88OS      LivingKitchen         10.0.1.200      ONLINE     3.5.0-0     dev      0.685      ON       ON       ON       OFF   
micr7c9ebd6147c4OS      node01                10.0.1.180      ONLINE     3.3.1-0     rel      0.280      ON       ON       OFF      OFF 

Other Developer commands

Development & Deployment & Connection:
  -f, --force_update    Force mode for -r/--update and -o/--OTA
  -e, --erase           Erase device
  -d, --deploy          Flash only the selected micropython image
  -i, --install         Copy the full precompiled micrOS tree
  -l, --list_devs_n_bins
                        List connected devices & micropython binaries.
  -ls, --node_ls        List micrOS node filesystem content.
  -u, --connect_via_usb
                        Connect via serial port - usb
  -b, --backup_node_config
                        Backup usb connected node config.
  -sim, --simulate      start micrOS on your computer in simulated mode
  -cc, --cross_compile_micros
                        Cross Compile micrOS system [py -> mpy] and optimize
                        precompiled web resources
  -gw, --gateway        Start micrOS Gateway rest-api server
  -v, --version         Get micrOS version - repo + connected device.

-cc copies micrOS/source/web into toolkit/workspace/precompiled/web, then overwrites the copied .js, .css, and .html files with optimized versions for deployment. Source web files stay readable.

Optional optimizer dependencies are installed by the normal toolkit bootstrap unless --light is used.

Socket terminal examples

The following output snapshots are from earlier releases. Device names, configuration keys, and output formatting may differ today; use the configuration reference for current defaults.

Identify device

devToolKit.py -c -p '--dev slim01 hello'
Load MicrOS device cache: /Users/bnm/Documents/NodeMcu/MicrOs/tools/device_conn_cache.json
Activate MicrOS device connection address
[i]         FUID        IP               UID
[0] Device: slim01 - 10.0.1.73 - 0x500x20x910x680xc0xf7
Device was found: slim01
hello:slim01:0x500x20x910x680xc0xf7:dev

Get help

devToolKit.py -c -p '--dev TinyDevBoard help'
[MICROS]
   hello     - device hello msg ID
   modules   - show active Load Modules
   version   - show micrOS version
   exit      - exit shell session
   reboot    - system soft reboot (vm), hard reboot (hw): reboot -h
   webrepl   - start webrepl, for file transfers use with --update
[CONF] Configuration mode
  conf       - Enter conf mode
    dump       - Dump all data, filter: dump [str]
    key        - Get value
    key value  - Set value
  noconf     - Exit conf mode
[TASK] Task operations
  task list         - list tasks by tags
  task kill [tag]   - stop task
  task show [tag]   - show task output
[EXEC] Command mode, syntax(...): <module> <function> <params> <postfix>
  Postfix hints:
    ... &[x]            - start one-shot task
    ... &&[x]           - start periodic task, where [x]: delay ms [x min: 20ms]
    ... >json           - request json formatted output
    ... >>hostname      - remote command execution (intercon)
help [all/-] [match]  - list Active/ALL modules with optional filtering

  cct
     help
  cluster
         help
  fileserver
            help

Load Modules - User defined functions

devToolKit.py -c -p '--dev BedLamp system info'

CPU clock: 24 [MHz]
Mem usage: 71.0 %
FS usage: 14.6 %
upython: v1.19.1 on 2022-06-18
board: ESP32 module with ESP32
mac: 7c:9e:bd:62:3f:f8
uptime: 0 1:29:19

SocketClient

Config:

micrOS/toolkit/user_data/device_conn_cache.json

{
    "__devuid__": [
        "192.168.4.1",
        9008,
        "__device_on_AP__"
    ],
    "__localhost__": [
        "127.0.0.1",
        9008,
        "__simulator__"
    ],
    "micr500291863428OS": [
        "10.0.1.72",
        9008,
        "BedLamp"
    ]
}

Interactive mode

devToolKit.py -c 
or
devToolKit.py --connect

[i]         FUID        IP               UID
[0] Device: __device_on_AP__ - 192.168.4.1 - __devuid__
[1] Device: __simulator__ - 127.0.0.1 - __localhost__
[2] Device: BedLamp - 10.0.1.72 - micr500291863428OS

Choose a device index: 2
Device was selected: ['10.0.1.72', 9008, 'BedLamp']
BedLamp $ help
<the command list shown in "Get help" above>
BedLamp $  exit
Bye!

Project structure

Historical source-tree snapshot; see the current runtime source and architecture guide for the maintained layout.

./micrOS/source
├── Common.py
├── Config.py
├── Debug.py
├── mespnow.py
├── Files.py
├── Hooks.py
├── InterConnect.py
├── Interrupts.py
├── Logger.py
├── Network.py
├── Notify.py
├── Scheduler.py
├── Server.py
├── Shell.py
├── Tasks.py
├── Time.py
├── Types.py
├── Web.py
├── main.py
├── micrOS.py
├── micrOSloader.py
├── reset.py
├── urequests.py
├── microIO.py
├── config
│   └── _git.keep
├── modules
│   ├── IO_esp32.py
│   ├── ...
│   ├── LM_ds18.py
│   ├── LM_esp32.py
│   ├── LM_espnow.py
│   ├── LM_gameOfLife.py
│   ├── LM_genIO.py
│   ├── LM_haptic.py
│   ├── LM_i2c.py
│   ├── LM_i2s_mic.py
│   ├── LM_keychain.py
│   ├── LM_ld2410.py
│   ├── LM_light_sensor.py
│   ├── ...
└── web
    ├── dashboard.html
    ├── index.html
    ├── ...

4 directories, 98 files

Roadmap

Version 3.X.0-0 micrOS-Waterbear

    Core:
    - Low power mode (wake on event, hibernate command)?
        - Remote controller / Sensor on battery UseCases

Version 3.X+1.0-0 micrOS-SecurePower

    Core:
    - Async socket servers with SSL/TLS integration (with auth.)
        - ShellCli (with TLS) and InterCon adaptation (default port: 9008, new secure port 9009)
        - WebCli (https) and webUI adaptation

    - Intercon-Wire (?)
        - Idea of wired message communication protocol same as Intercon-Shell/Intercon-ESPNow
        - Possible HW protocols: i2c / onewire / uart BUT it should support bidirectional message transfers
        - Goal: CoProcessor easy integration feature - Arduino env support

    - Application deployment automation: /config/compose.json
        - enables application deployment:
            - configuration (node_config.json) handling - safe parameter injection (boothook and irqs)
            - [done] requirements.txt handling
        - Automatic behaviour in core system if file exists in STA mode

Release history

Development Metrics

Documentation map

• Architecture
• Load Module development
• Contributing
• MicroPython images
• Gateway deployment
• Advanced use reference

Operations and maintainer notes

• Save screen console buffer (output) Press ctrl + A : and type hardcopy -h <filename>

• Create a call graph: PyCallGraph documentation (legacy tool).

• Convert PNG/JPG-s to GIF: convert -delay 60 ./*.png mygif.gif

• micrOS core and Load Module source code info:

devToolKit.py -lint
# Or use the long option:
devToolKit.py --linter

micrOS gateway - Linux service template

[BETA] service setup tool: toolkit/helper_scripts/linux_service/make.bash

• Prerequisite: install micrOS devtoolkit PiP package

• Create service: micrOS gateway service

• [1] Create micros-gw.service. Replace the credentials, working directory, user, and Python executable path for your installation. If you use a shell wrapper instead, set ExecStart to /bin/bash followed by that script's path.

[Unit]
Description=micrOS gateway REST API service
After=network-online.target

[Service]
Environment="API_AUTH=<usr_name>:<password>"
ExecStart=/usr/bin/python3 -m devToolKit -gw
WorkingDirectory=/home/gateway
StandardOutput=inherit
StandardError=inherit
Restart=always
User=<user>

[Install]
WantedBy=multi-user.target

• [2] copy service to sudo cp micros-gw.service /lib/systemd/system/

• [3] start service: sudo systemctl start micros-gw.service

• [4] enable service at bootup: sudo systemctl enable micros-gw.service

• [5] show service state: sudo systemctl status micros-gw.service

Git maintenance

• Add git tag: git tag -a vX.Y.Z-K -m "tag message"

• Publish tags: git push origin --tags

• Pretty git view: git log --pretty=oneline

• File change list: git diff --name-only fbb4875609a3c0ee088b6a118ebf9f8a500be0fd HEAD | grep 'mpy-MicrOS'

• GitHub embed youtube link: https://github.com/itskeshav/Add-youtube-link-in-Readme.md

• Git history visualization with Gource

gource \
    --highlight-users \
    --hide filenames \
    --file-idle-time 0 \
    --max-files 0 \
    --seconds-per-day 0.01 \
    --auto-skip-seconds 1 \
    --title "micrOS Evolution" \
    --output-ppm-stream - \
    | ffmpeg -y -r 30 -f image2pipe -vcodec ppm -i - -vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 output.mp4

git push -u origin master