Initial release (#2)

Author: vshymanskyy

.gitignore

@@ -0,0 +1,3 @@
+**/__pycache__/
+.DS_Store
+

README.md

@@ -1 +1,99 @@
-# Blynk-MicroPython-Edgent
+
+# Blynk.Edgent for MicroPython
+
+Blynk provides custom MicroPython builds specifically designed for IoT applications.
+These builds offer a standard MicroPython environment, enriched with numerous fixes, improvements,
+and additional features such as **secure Blynk.Cloud connection, device claiming and provisioning, OTA updates, configuration storage**, [and more](#features).
+
+## Getting Started
+
+- Sign up/Log in to your [Blynk Account](https://blynk.cloud)
+- Install **Blynk IoT App** for [iOS](https://apps.apple.com/us/app/blynk-iot/id1559317868) or [Android](https://play.google.com/store/apps/details?id=cloud.blynk)
+
+## 1. Install MicroPython + Blynk.Edgent
+
+<details>
+  <summary>See instructions for <b>ESP32</b> based devices</summary></br>
+
+You can use [**ESP Launchpad**](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://blynk-fw-builds.fra1.cdn.digitaloceanspaces.com/Blynk-Edgent-MicroPython/latest/esp-quickstart.toml) to flash your device. You will need a Chrome-based browser.
+
+1. Plug your board into a USB port
+2. Click <kbd>Connect</kbd> in upper right corner and select your board
+   - Recommended: click <kbd>Erase Flash</kbd> on the **DIY** tab
+4. Select **Application** (generic boards vs specialized builds)
+5. Select **Develop Kit** variant based on flash size and type
+6. Click the <kbd>Flash</kbd> button (if disabled, try clicking the `Connect` button again)
+7. Press <kbd>Reset</kbd> button on your board to run the MicroPython firmware
+
+> Alternatively, you can [flash your ESP32 device manually](https://github.com/Blynk-Technologies/Blynk-MicroPython-Edgent/releases/latest)
+
+</details>
+
+<details>
+  <summary>See instructions for <b>Raspberry Pi Pico W</b></summary></br>
+
+1. Hold down the <kbd>BOOTSEL</kbd> button while plugging the board into a USB port
+2. Copy the latest [UF2 firmware file](https://blynk-fw-builds.fra1.cdn.digitaloceanspaces.com/Blynk-Edgent-MicroPython/latest/RPI_PICO_W.uf2) to the USB mass storage device that appears
+3. Once programming of the new firmware is complete, the device will automatically reset and be ready for use
+
+</details>
+
+## 2. Connect your device to Blynk.Cloud
+
+1. Open **Blynk IoT App** on your smartphone
+2. Click **Add device** -> **Find devices nearby**
+3. Select your device and follow the setup instructions
+
+> [!NOTE]
+> If you have already created your device in Blynk,
+> you can [connect it manually using REPL](_extra/Cookbook.md#manual-device-connection)
+
+## 3. Edit the default MicroPython app
+
+The [`main.py`](./main.py) is a simple `asyncio`-based script that defines the high level device operation.
+It could be as simple as this:
+
+```py
+from blynk import edgent
+from time import ticks_ms
+from asyncio import sleep_ms
+
+async def publisher_task():
+    while True:
+        await sleep_ms(1000)
+        edgent.publish("Uptime", ticks_ms())
+
+edgent.run_asyncio_loop([
+    publisher_task()
+])
+```
+
+There are many ways to program your device. Here, we'll guide you through the two most popular options:
+
+- [ViperIDE for Web and Mobile](_extra/Workflow-ViperIDE.md)
+- [CLI using mpremote](_extra/Workflow-CLI.md)
+
+# Features
+
+- `blynk.inject` - BLE-assisted device claiming and provisioning
+- `blynk.air` - OTA updates using **Blynk.Console** and **Blynk.Apps**
+- `blynk.time` - Time Zone handling (including DST transitions), Sunrise/Sunset calculation
+- `blynk.repl` - Remote MicroPyhton REPL for Blynk Terminal
+- `netmgr` - Network management for `WiFi`, `Ethernet` and `Cellular`
+- `config` - System-wide configuration
+- `aiontp` - A versatile asyncio-based version of NTP client
+- `aioinput` - An asyncio variant of `input` function
+- `aioprof` - Asyncio [profiling tool](https://gitlab.com/alelec/aioprof)
+- `logging` - System-wide, preconfigured logging
+- `board` - A unified way to access the board peripherals
+- Factory reset function
+- Support for TLS certificate bundles
+- For `ESP32`:
+  - `coredump` - Collect crash reports remotely
+  - OTA updates for MicroPython system firmware
+
+# Further reading
+
+- [Cookbook](_extra/Cookbook.md)
+- [`asyncio` documentation](https://docs.micropython.org/en/latest/library/asyncio.html)
+- [`asyncio` tutorial](https://github.com/peterhinch/micropython-async/blob/master/v3/docs/TUTORIAL.md)

_extra/Cookbook.md

@@ -0,0 +1,106 @@
+
+# MicroPython + Blynk.Edgent Cookbook
+
+## Manual device connection
+
+Connect your device to Blynk.Cloud by directly modifying the device configuration using REPL:
+
+```py
+# Add your WiFi network
+sysconfig["nets"].append({ "type": "wlan", "ssid": "YourSSID", "psk": "YourPassword" })
+
+# Setup Blynk Template and Auth Token
+sysconfig["blynk"].update({
+    "tmpl_id":   "TMPxxxxxxxxxx",
+    "tmpl_name": "Device",
+    "auth":      "rn60Wxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "server":    "blynk.cloud",
+})
+
+# Save system configuration
+sysconfig.commit()
+
+# Restart
+import machine
+machine.reset()
+```
+
+> [!NOTE]
+> When entering the production phase, you can **pre-configure** these settings and enable the **Factory Reset** function. Please contact Blynk for guidance.
+
+## Edit System Config
+
+You can edit `sysconfig` directly from MicroPython REPL:
+
+```py
+# Display complete sysconfig
+sysconfig
+
+# Display parts of sysconfig
+sysconfig.keys()
+sysconfig['blynk']
+
+# Enable color logs and set log level
+sysconfig["log"].update({ "color": True, "level": "debug" })
+
+# Add your WiFi network
+sysconfig["nets"].append({ "type": "wlan", "ssid": "YourSSID", "psk": "YourPassword" })
+
+# Remove network by index (0-based)
+del sysconfig["nets"][2]
+
+# Remove all networks
+sysconfig['nets'].clear()
+
+# Save system configuration
+sysconfig.commit()
+```
+
+## Add diagnostics
+
+```py
+import netmgr
+import micropython
+import gc
+
+async def diagnostics_task():
+    while True:
+        mem_prev = gc.mem_free()
+        gc.collect()
+        mem_free = gc.mem_free()
+        gc.threshold(mem_free // 4 + gc.mem_alloc())
+        edgent.publish("ds/Heap Free", mem_free / 1024)
+        edgent.publish("ds/GC Collect", (mem_free - mem_prev) / 1024)
+        edgent.publish("ds/WiFi RSSI", netmgr.sta.status("rssi"))
+        await asyncio.sleep(60)
+```
+
+Also, add `diagnostics_task()` to `edgent.run_asyncio_loop`.
+
+## Watchdog Timer (WDT)
+
+The watchdog is typically disabled by default, as it can complicate prototyping.
+It is recommended to enable it at later stages of development:
+
+```py
+sysconfig["wdt"]["enabled"] = True
+sysconfig.commit()
+machine.reset()      # Changing this setting requires a hard reset
+```
+
+## Format internal FS
+
+> [!WARNING]
+> This performs a factory reset, the internal file system will recover to it's initial state
+
+```py
+from blynk import edgent
+edgent.factory_reset()
+```
+
+## Update MicroPython firmware directly from GitHub (ESP32 only)
+
+```py
+from blynk import air
+air.start_ota_update("https://micropython.org/resources/firmware/ESP32_GENERIC-SPIRAM-20240222-v1.22.2.app-bin", validate=False)
+```

_extra/Workflow-CLI.md

@@ -0,0 +1,56 @@
+
+# Using `mpremote`
+
+Make sure your board is connected via USB. It should **not** be opened by any serial monitor or other tool.
+Run these commands on your development machine:
+
+```sh
+# Install mpremote utility
+pip3 install --upgrade mpremote
+
+# Copy the example files to the device
+mpremote cp main.py :
+```
+
+> [!NOTE]
+> If you have any issues with this, please check out the [`mpremote` documentation](https://docs.micropython.org/en/latest/reference/mpremote.html)
+
+Then, open MicroPython REPL:
+
+```sh
+mpremote repl
+```
+
+Press `Ctrl+D` to restart your app.
+
+The device should get connected in a few seconds:
+
+```log
+      ___  __          __
+     / _ )/ /_ _____  / /__
+    / _  / / // / _ \/  '_/
+   /____/_/\_, /_//_/_/\_\
+          /___/
+
+Connecting to WiFi_SSID... OK: 192.168.1.123
+Connecting to MQTT broker...
+Connected to Blynk.Cloud [secure]
+```
+
+# Create OTA package
+
+The `cfg/fw.json` will be used to identify the firmware version and type.
+Firmware type should match the Blynk Template ID, unless:
+- You have a single product that requires differant firmware upgrade packages
+- You have multiple products that use a single firmware
+
+```sh
+python3 _extra/tools/upy-pack.py -o app_ota.tar.gz main.py cert/ca-bundle.pem `find ./lib -name '*.py'`
+```
+
+---
+
+# Further reading
+
+- [Cookbook](Cookbook.md)
+

_extra/Workflow-ViperIDE.md

@@ -0,0 +1,9 @@
+
+TODO
+
+---
+
+# Further reading
+
+- [Cookbook](Cookbook.md)
+

_extra/boards/generic-esp32.py

@@ -0,0 +1,26 @@
+from machine import Pin, RTC
+import sys, network
+
+board_id = "Generic ESP32"
+
+class Board:
+    sta = None
+    rtc = None
+
+_board = Board()
+
+def rtc():
+    if _board.rtc is None:
+        try:
+            _board.rtc = RTC()
+        except Exception as e:
+            sys.print_exception(e)
+    return _board.rtc
+
+def sta():
+    if _board.sta is None:
+        try:
+            _board.sta = network.WLAN(network.STA_IF)
+        except Exception as e:
+            sys.print_exception(e)
+    return _board.sta

_extra/boards/generic-w600.py

@@ -0,0 +1,26 @@
+from machine import Pin, RTC
+import sys, network
+
+board_id = "Generic W600"
+
+class Board:
+    sta = None
+    rtc = None
+
+_board = Board()
+
+def rtc():
+    if _board.rtc is None:
+        try:
+            _board.rtc = RTC()
+        except Exception as e:
+            sys.print_exception(e)
+    return _board.rtc
+
+def sta():
+    if _board.sta is None:
+        try:
+            _board.sta = network.WLAN(network.STA_IF)
+        except Exception as e:
+            sys.print_exception(e)
+    return _board.sta

_extra/boards/rpi-pico-w.py

@@ -0,0 +1,17 @@
+from machine import Pin
+import sys, network
+
+board_id = "Pi Pico W"
+
+class Board:
+    sta = None
+
+_board = Board()
+
+def sta():
+    if _board.sta is None:
+        try:
+            _board.sta = network.WLAN(network.STA_IF)
+        except Exception as e:
+            sys.print_exception(e)
+    return _board.sta