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 (USB, OTA).
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
- [NEW] Installer: microsctl
- 📦 Applications · micrOS Packages
- 🌐 Network modes · Configuration reference
- 💬 Tutorials and community
- ⚙️ Advanced use — automation, hardware, configuration, and developer tools
- 🧩 Create a Load Module · Architecture
- 📚 Documentation map
The on-device web UI: REST console, configuration, application controls, and file management. It is enabled automatically when the board has enough memory.
Why micrOS?
- One function, several ways to use it. Public functions in
LM_*.pyLoad 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. See boards and memory for larger applications.
Firmware Catalog, details: firmware catalog
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
if your platform genuinely requires a USB-driver installation. Repository
cloning and magic.bash are maintainer workflows documented separately in the
maintainer appendix.
2. Deploy micrOS over USB
Start the graphical toolkit:
devToolKit.py
Warning: Deploy (USB) erases the board's existing firmware and files. Back up a board you already use before continuing.
- Connect your board over USB.
- Select the matching board and MicroPython firmware from the available lists.
- Select Deploy (USB) and confirm the operation.
- 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. 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:
- Connect your computer to the
node01Wi-Fi network using the factory passwordADmin123. - Open
http://192.168.4.1in a browser. Keep that connection active even if your computer reports that the network has no internet access. - Select 🚀 Load Web Apps, then open Configuration.
- In Device, set Device name to a unique, URL-friendly name such as
MyNode. Under Startup Actions, optionally addweb load. This makes default web applications loading persistant (not need to run Load Web Apps after every reboot...) - In Network, enter the WiFi SSID and WiFi Password for your local
network. The default network mode is
STA. - As a security precaution, replace the factory Admin Password in Device. It must be 8–9 characters long and contain uppercase and lowercase letters and a digit.
- Select 💾 Save, then Reboot when the confirmation dialog appears.
The HTTP server is enabled by default. At boot, micrOS checks the available heap
and disables it automatically if its 80 KiB memory budget cannot be met. The
web load startup action always enables default web applications at
boot time.
After the node restarts, reconnect your computer or phone to the normal local
network and open http://MyNode.local.
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.
Device discovery
devtoolkit.py -s -stat
[ 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
micrXXXXXXXXXXXXOS Entrance 10.0.1.55 ONLINE 3.5.0-0 rel 0.181 ON OFF OFF OFF
micrXXXXXXXXXXXXOS LivingKitchen 10.0.1.200 ONLINE 3.5.0-0 dev 0.667 ON ON ON OFF
Security boundary: micrOS currently serves HTTP and its socket shell without transport encryption, and shell authentication is disabled by default. Use nodes only on a trusted local network. Do not expose ports 80 or 9008 directly to the internet. Changing
appwdprotects the access point and protected operations; it does not add TLS to HTTP or the socket protocol.
Advanced: Configuration with Shell
micrOS Shell is the Operation and Maintenance interface (OAM), it is always available.
Use this method when the board cannot host the web UI because of its memory
limit, or when browser-based configuration is unavailable. Start
devToolKit.py -s -c, select __device_on_AP__ at 192.168.4.1, and enter the
following commands one line at a time. Replace the angle-bracket
placeholders, including the brackets, and check that each setting succeeds.
conf
devfid MyNode
staessid <your-wifi-name>
stapwd <your-wifi-password>
appwd <new-device-password>
boothook web load
noconf
reboot
If the board does not have enough memory for the web UI, omit
boothook web load and continue using ShellCli.
After the reboot, reconnect through DevToolKit and continue with the validation in step 4.
4. Confirm the installation
- Open
http://MyNode.local/rest/system/infoto call the first REST endpoint, - Connect through DevToolKit and try the shell
devToolKit.py -s -c(search and connect):
help
system info
system heartbeat
system info reports the board, MicroPython version, memory, filesystem, and
uptime. system ifconfig reports network mode and addresses. help all lists
the installed Load Modules. You can also 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. Keep the configuration reference nearby for exact settings and scheduling syntax; continue to Advanced use for custom behavior, 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.
Networking modes
A node normally joins the local Wi-Fi network in station mode. It can fall back to its own access point for configuration. Clients communicate directly with a node; nodes can invoke each other over sockets or ESP-NOW. The complete behavior and parameter definitions are in the configuration and automation reference.
Node configuration reference (web)
For routine setup, open http://<nodename>.local/config. The settings most new
users need are:
| Setting | Purpose |
|---|---|
devfid |
Node name, AP name, DHCP hostname, and shell prompt after restart. |
staessid, stapwd |
Local Wi-Fi network credentials. Multiple networks use ;-separated values. |
appwd |
Shared password for the AP, protected operations, and optional shell authentication. Replace the factory value. |
boothook |
Startup commands such as web load; rgb load. Preserve existing commands when adding one. |
nwmd |
Preferred station (STA) or access-point (AP) mode. |
The complete configuration and automation reference documents every key, default, type, reboot requirement, authentication behavior, and scheduling syntax.
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, customization, and shell usage
- Documentation
- Roadmap · Release history
Interfaces and applications
| Interface | Purpose |
|---|---|
| On-device web UI | Configuration, generated dashboards, REST tools, and file management at http://<nodename>.local. |
| WebCli / REST | Exposes MicroPython module functions through HTTP endpoints. |
| ShellCli | Provides a generic, session-based TCP/IP operation and management (OAM) interface with a telnet-style shell. |
| DevToolKit | Deploys, updates, discovers, monitors, and simulates nodes. |
| InterCon | Executes commands between nodes over sockets or ESP-NOW. |
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
Run web load fileserver=True in the shell. To make it persistent, add the
command to boothook while preserving existing startup actions. See the
configuration reference
for details and security behavior.
Configure automation
Startup and network settings
Use the Configuration app for routine changes. boothook can initialize the
web applications and hardware modules in sequence, for example:
web load; rgb load; neopixel load
Preserve existing actions when adding another one. ShellCli remains the fallback when the web UI is unavailable.
Schedules and external events
| Mechanism | Configuration and example |
|---|---|
| Periodic timer | Enable timirq; set timirqseq in milliseconds and timirqcbf to a command. With 5000 and bme280 measure, Timer(0) measures every five seconds. Callbacks support # comments. |
| Cron | Enable cron and set crontasks. Timer(1) runs timestamped entries such as *:8:0:0!rgb rgb r=10 g=60 b=100 (daily at 08:00). |
| External interrupt | Enable irqX (X = 1–4), choose irqX_trig (up, down, or both), and set irqX_cbf to a Load Module callback. Callbacks support # comments. |
The complete automation reference covers cron fields and ranges, multi-command separators, comments, sunrise/sunset offsets, timer dependencies, and IRQ configuration.
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. A pin map alone does not guarantee compatibility: check the firmware catalog and each module's requirements. The full web UI plus several modules generally needs more than 150–200 KB of available RAM; PSRAM-capable boards are preferable for larger combinations, camera, or audio workloads. See the hardware and memory guide for board examples, historical measurements, and port-specific caveats.
Built-in peripheral support
Sensors, inputs, actuators, and outputs are documented in the generated Load Module catalog. The hardware guide links to that catalog and records the related wiring and memory caveats.
Device pinouts for wiring
microIO maps logical application pins through IO_*.py board definitions.
Inspect the active mapping with system pinmap; individual pins can be
overridden through cstmpmap. The hardware guide
contains the complete mapping list, override syntax, OTA caveat, and wiring
illustrations.
Gateway and monitoring
The optional Gateway provides multi-node access and can feed Prometheus metrics to Grafana dashboards. The Docker setup guide contains the compose command, scraper configuration, dashboard examples, standalone container options, and the official DockerHub image.
Roadmap
Proposed low-power, secure-transport, wired InterCon, and compose-based deployment work is preserved in Project roadmap and release history. These are proposals rather than committed release promises.
Release history
The complete historical milestone table, memory figures, release-note links, legacy-client references, and development metrics are in Project roadmap and release history. It is explicitly labeled historical so it is not mistaken for the current firmware compatibility matrix.
Documentation map
- Configuration and automation reference
- Hardware, memory, and pin-map guide
- Architecture
- Development, shell usage, and Load Modules
- MicroPython images
- Gateway deployment
- Project roadmap and release history
- Business vision
- Contributing
- Maintainer operations
git push -u origin master
1 maintainer
Release files for micrOSDevToolKit 3.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| microsdevtoolkit-3.6.2.tar.gz | 21.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| microsdevtoolkit-3.6.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 42.8 MB
Release files / microsdevtoolkit-3.6.2.tar.gz
| Download URL | microsdevtoolkit-3.6.2.tar.gz |
|---|---|
| Size | 21.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b016dc911eda8cdb5732b3dbea06eb8b77d43b23b8744808852c119fc055a85a
|
|
BLAKE2b-256 checksum How to use checksums |
43289ad987a9258c7f185b95348866ccf1912a41bbab0d44df7d5e5c5dd4cc02
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / microsdevtoolkit-3.6.2-py3-none-any.whl
| Download URL | microsdevtoolkit-3.6.2-py3-none-any.whl |
|---|---|
| Size | 21.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c3010c22c2b1dd03f58396b2dba715a1585d3f02ee46d87304f281fbcff0f719
|
|
BLAKE2b-256 checksum How to use checksums |
6f38009c74a934a1f084b793b0c63fd21a58b3220a8aaa05f3e7111566d61927
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
