[Issue #5] - Adding setup instruction step to install all dependencies via requirements.txt

README.md

@@ -1,18 +1,59 @@
 # pico-thermo
 
-MicroPython app to read data from BME280 sensor and send it to Home Assistant
+![Woodpecker CI badge](https://builds.metaunix.net/api/badges/90/status.svg)
+![shields.io version badge](https://img.shields.io/gitea/v/release/BitGoblin/pico-thermo?gitea_url=https://git.metaunix.net)
 
-## Running
+A [MicroPython](https://micropython.org/) app to read data from BME280 sensor and send it to Home Assistant.
 
-Flash your Raspberry Pi Pico with MicroPython.
+## Hardware
 
-Copy `config.example.py` to `config.py` and edit the settings to match your environment.
+The following hardware is what I used for a deployment:
 
-Copy `main.py` and `config.py` to the root of the filesystem on the Pico.
+* Raspberry Pi Pico 2 W: https://www.amazon.com/dp/B0DRJXPPWL
+  * The **W** is VERY important, as without networking it can't reach Home Assistant!
+  * Also a Raspberry Pi Pico W *should* work too, but I haven't tested it yet
+* Waveshare Bosch BME280 sensor: https://www.amazon.com/dp/B07Q47DFXS
+* Elegoo SSD1306 LCD: https://www.amazon.com/dp/B0FSRQG23K
 
-Connect the BME280 sensor to your Pico and power on.
+Most (or all?) of these components can be swapped for equivalent components. You just need to make sure the code is compatible with whatever board you choose (not likely), is a genuine BME280 sensor, and an SSD1306 display.
 
-Head on to your Home Assistant instance and enjoy!
+Support for other hardware types may come in the future, but if there's a specific sensor or board you're interested in, please submit an issue or pull request!
+
+### Prototyping
+
+To help with debugging/testing deployments, I also used these components:
+
+* Elegoo 400-pin Breadboard: https://www.amazon.com/dp/B01EV640I6
+* Freenove Raspberry Pi Pico Breakout Board: https://www.amazon.com/dp/B0BFB53Y2N
+* Elegoo 20cm Jumper Cables 120 count: https://www.amazon.com/dp/B01EV70C78
+
+These are not necessary to run the app, but can be useful for testing and/or flashing several nodes.
+
+## Software Deployment
+
+### Requirements
+
+* [MicroPython](https://micropython.org/download/) - MicroPython downloads
+* [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) - MicroPython remote serial tool
+* (Linux users) Your user should be a part of the `dialout` group
+
+### Steps
+
+1. Connect your BME280 sensor and SSD1306 display to your Pico.
+    1. You *may* need a breadboard for this, else you can use splitters.
+2. Connect your Pico to your PC via a micro-USB to USB type-A cable.
+3. [Flash your Raspberry Pi Pico with MicroPython](https://docs.micropython.org/en/latest/rp2/tutorial/reset.html).
+    1. This has been tested with MicroPython 1.29, but other versions should work.
+4. Clone this git repository: `git clone https://git.metaunix.net/BitGoblin/pico-time`.
+5. `cd` into the repo: `cd pico-time`.
+6. Install Python dependencies via mpremote: `xargs mpremote mip install < requirements.txt`.
+7. Copy `config.example.py` to `config.py` and edit the settings to match your environment.
+8. Copy the Python code over to the Pico:
+    1. `mpremote cp main.py :main.py`
+    2. `mpremote cp config.py :config.py`
+9. Reset the Pico: `mpremote reset`
+
+If it worked you should see the display show a message about connecting to WiFi, then eventually a readout of the current temperature to the SSD1306 display. If it failed, you can monitor the app via `mpremote repl` or using an IDE like [Thonny](https://thonny.org/).
 
 ## License
 

main.py

@@ -259,7 +259,7 @@ def register_ha_discovery(mqtt):
 
 
 # -------------------------------------------------------------
-# Main Execution Loop
+# Instantiate Wi-Fi connection
 # -------------------------------------------------------------
 def connect_wifi():
     wlan = network.WLAN(network.STA_IF)
@@ -277,6 +277,22 @@ def connect_wifi():
     print(f"Wi-Fi connected. IP: {wlan.ifconfig()[0]}")
 
 
+# -------------------------------------------------------------
+# Panic when the sensor isn't ready
+# -------------------------------------------------------------
+def panic(err=None):
+    """Signals a fatal fault by blinking the onboard LED continuously."""
+    if err:
+        print(f"Fatal error: {err}")
+    led = Pin("LED", Pin.OUT)
+    while True:
+        led.toggle()
+        time.sleep(0.1)
+
+
+# -------------------------------------------------------------
+# Main Execution Loop
+# -------------------------------------------------------------
 def main():
     # Adjust SDA/SCL pins according to your wiring
     i2c = SoftI2C(sda=Pin(16), scl=Pin(17), freq=100000)
@@ -322,4 +338,13 @@ def main():
 
 
 if __name__ == "__main__":
+    # Allow 3.3V power rails and I2C registers to settle on cold boot
+    time.sleep(2)
+
+    # Indicate startup has begun
+    Pin("LED", Pin.OUT).on()
+
+    try:
         main()
+    except Exception as e:
+        panic(e)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pico-thermo"
-version = "0.1.0"
+version = "0.1.1"
 description = "MicroPython MQTT app to read BME280 sensor into Home Assistant"
 readme = "README.md"
 requires-python = ">=3.9"