Updated README.md

README.md

@@ -1,159 +1,117 @@
-# SulaJalmari
+# Octopus Flex PCB (SulaJalmari)
 
-nRF 52840 -pohjainen pöytälelu/opetustyökalu.
+An nRF52840-based desk toy where art and engineering collide. 
 
 ## Table of Contents
 
-- [Intro](#intro)
-- [Ominaisuudet](#ominaisuudet)
-- [Vaatimukset](#vaatimukset)
-- [Käyttö](#käyttö)
-- [Ohjelmointi](#ohjelmointi)
-- [Resurssit](#resurssit)
+* [Introduction & The Point](#introduction--the-point)
+* [Hardware Specifications](#hardware-specifications)
+* [Fun Features & Known Flaws](#fun-features--known-flaws)
+* [Software](#software)
+* [Programming & Usage](#programming--usage)
+* [Open Source Resources](#open-source-resources)
 
-## Intro
+---
 
-### SulaJalmari on nRF52840-pohjainen opetustyökalu ja pöytälelu, joka on suunniteltu tarjoamaan käytännönläheistä oppimiskokemusta sulautetuista järjestelmistä ja IoT-teknologioista.
+## Introduction & The Point
 
-<img src="pics/Device.jpg" height=600> 
+The Octopus Flex PCB (SulaJamlari) is a desk toy intended to provide a hands-on learning experience with embedded systems, IoT technologies, and PCB design. 
+
+People often ask what the "point" of this project is, but there isn't a strictly functional one. It was created to see what happens when art meets engineering, to learn device development, and to be a challenge. The point was the journey—and, of course, because an octopus desk toy looks incredibly cool.
+
+---
+
+## Hardware Specifications
+
+This section covers the exact specifications of the third (and final) prototype:
+
+* **Board Structure:** 2x Flex PCBs (acting as the octopus head and legs) and 1x FR4 PCB (acting as the base board).
+* **MCU:** nRF52840-QIAA (soldered directly to the flex PCB with a stiffener on the reverse side).
+* **IMU:** ICM-20602 accelerometer (shares an interrupt line with the light sensor).
+* **Light Sensor:** XYC-ALS21C-K1 I2C ambient light sensor (shares an interrupt with the IMU).
+* **Leg LEDs:** 8x Blue LEDs running at 2mA (LED0603-RD).
+* **Eye LEDs:** 2x Addressable RGB LEDs (WS2812B-2020).
+* **Power & Battery:** TP4054 50mA battery charger, ME6211C22M5G-N 3V3 LDO, and XC6206P362MR 3V6 LDO (dedicated to the addressable LEDs).
+* **Connectivity:** Bluetooth with a minimal PCB trace antenna, USB-C for power/programming, and a 5V rail to chain multiple devices together.
+* **Audio & Haptics:** Buzzer with a driving transistor, plus a footprint for a vibration motor (motor ultimately not installed in the final version).
+* **Interface:** 2x tactile user buttons, 1x tactile reset button, and an on/off switch.
+* **Debugging:** Base board debugging pins compatible with a standard ~$3 DAPLink debugger via pyOCD/OpenOCD.
+* **Aesthetics:** Silkscreen suction cups and mouth.
+
+---
+
+## Fun Features & Known Flaws
+
+### The Fun Things
+* **Wobble Physics:** Because the assembled PCBs take the physical shape of an octopus, the whole device wobbles when shaken.
+* **Visible PWM:** When the device is wobbling and the LEDs are running PWM, the movement actually allows you to see the PWM strobing with your naked eye.
+* **Tap-to-Click:** The IMU is mounted in the very top of the head. This means you can tap the top of the device, and the accelerometer registers it as a physical button press.
+
+### The Flaws (Lessons Learned)
+* **Durability Limits:** During "stress testing" (read: repeatedly slamming it against the base board), some of the MCU pins eventually detached. Please don't torture the electronics!
+* **Haptics:** The vibration motor was mostly unnoticeable, leading to its removal from the final assembly. (Pins to connect a motor still exist)
+* **Logistics:** Transporting an assembled, multi-layered flex-PCB octopus safely is tricky.
+
+---
+
+## Software
+
+### Zephyr Framework
+Initially, Zephyr felt overwhelming due to deprecated documentation and a steep learning curve with devicetrees. However, to get the Bluetooth functionality we wanted, we gave it another shot. Eventually ended up enjoying having "one framework to rule them all", plus gaining embedded Linux/devicetree experience was highly valuable. The custom board files use the `nrf52840-dk` as a template. Zephyr relies on **MCUboot** as its bootloader.
+
+### Arduino Support
+For broader accessibility, the Adafruit nRF52 library and bootloader was modified to work with the Octopus Flex PCB in the Arduino IDE.
+
+---
+
+## Programming & Usage
 
 
-## Ominaisuudet
+### Development Prerequisites
+If you want to build custom Zephyr firmware, you need the **nRF Connect SDK**, the `Board` folder from this repository, and your `prj.conf` file. The easiest way to start is by installing the **nRF Connect for VS Code** extension. The current project is verified to work with SDK version **2.6.1**.
 
-### Hardware: 
-- 2x RGB LED (silmät)
-- 8x sininen LED (jalat)
-- Kiihtyvyysanturi
-- Tärinämoottori
-- Piippari
-- Bluetooth
-- USB-C
+### Building the Firmware
+If you are modifying the code, ensure your `prj.conf` contains the following line so Zephyr generates the signed hex file required by the bootloader:
 
-### Software:
-- Bootloader
-- Valmiita demo-koodeja
-- Ohjelmoitavissa USB:n yli
-
-## Vaatimukset
-
-### Demot
-Demojen ohjelmoimiseen tarvitset nRF Connect for Desktop -ohjelmointityökalun ja tästä Git-reposta löytyvien demokoodien app_signed.hex-tiedostot. Tämän jälkeen siirry kohtaan: [Ohjelmointi](#ohjelmointi)
-
-### Kehitys
-Kehitystä varten tarvitset vähintään nRF Connect SDK:n ja tästä Git-reposta löytyvät "Board"-kansion tiedostot sekä pjr.conf-tiedoston. Suositeltavaa on kuitenkin aloittaa valmiista demokoodista, jossa tulee mukana kaikki tarpeelliset tiedostot ja kyseiseen demoon räätälöity pjr.conf-tiedosto. Parhaiten pääset alkuun asentamalla "nRF Connect for VS Code" -lisäosan Visual Studio Codeen. nRF Connect for VS Code -lisäosasta pääset asentamaan vaatimukset.
-
-![Manage SDK](pics/Manage.png)
-<br>
-Tarvitset toolchainin sekä SDK:n.
-<br>
-
-![Install SDK](pics/Install.png)
-<br>
-Valitse Install SDK/Toolchain -valikosta, ja valitse sen jälkeen versio, jonka haluat asentaa. Tämän hetkinen versio on rakennettu ja todettu toimivaksi version 2.6.1 kanssa.
-<br>
-
-![SDKVER](pics/SDKVER.png)
-<br>
-
-## Käyttö
-
-### Aloitus
-
-Toolchainin sekä SDK:n asentamisen jälkeen voit avata valmiin demokoodin nRF Connect for VS Code -lisäosasta.
-
-![Open](pics/OpenExisting.png)
-
-Sovelluksen valinnan jälkeen voit aloittaa ohjelmoinnin src-kansiosta löytyvien tiedostojen avulla.
-
-![Files](pics/ProjectView.png)
-
-### Valmiin sovelluksen ohjelmointi laitteelle
-
-#### Build Configuration
-
-Build configuration vaaditaan sovelluksen build-vaihetta varten. Build configurationin voi luoda nRF Connect -lisäosan "Applications" tai "Build Configuration" -osiosta painamalla "Add Build Configuration". Mikäli "Applications"-osiossa näkyy valmis build configuration, tai projektissa on valmiiksi olemassa "Build"-kansio etkä ole itse niitä lisännyt, poista build configuration ja kansio ennen uuden lisäämistä. Toisella laitteella lisätyt build configurationit eivät välttämättä toimi laitteellasi.
-
-Jos noudatit kehitysvaiheen ohjeita, "Add Build Configuration" -ikkunassa painaessasi "Custom Board" -valintaa, listasta löytyy laitteelle valmiiksi luotu board-tiedosto "nrf52840_qalmari".
-
-![Build](pics/Build.png)
-
-Painamalla "Build Configuration" -painiketta lisäät build configurationin projektiisi. Tämän jälkeen sen tulisi löytyä "Applications" -ikkunasta nRF Connect -lisäosasta.
-
-#### Build
-
-Jos et käyttänyt valmista demokoodia ohjelmoinnin pohjana, varmista pjr.conf-tiedoston sisältö. Laitteen bootloader vaatii ohjelmoidessaan tietyn tunnisteen, jonka Zephyr kirjoittaa app_signed.hex-tiedostoon automaattisesti vain, jos pjr.conf-tiedostosta löytyy rivi: 
-```
+```text
 CONFIG_BOOTLOADER_MCUBOOT=y
 ```
-Ilman tätä riviä Zephyr ei luo app_signed.hex-tiedostoa, eikä laitetta voi ohjelmoida USB:n yli.
 
-Varmista myös että projektin sisältä lyötyy "child_image" kansio, mikäli kansiota ei löydy, luo se itse ja lisää sen sisälle "mcuboot.conf" niminen tiedosto, ja kirjoita sen sisälle rivi:
-```
+You must also ensure a `child_image` folder exists in your project with an `mcuboot.conf` file containing:
+
+```text
 CONFIG_PM_PARTITION_SIZE_MCUBOOT=0x12000
 ```
 
-![Build](pics/child_image.png)
+Running a Build via the VS Code extension will generate the required file at: `main_project/build/zephyr/zephyr.signed.hex`.
 
+### Flashing via USB
+1. Open **nRF Connect for Desktop** and launch the **Programmer** app.
+2. Click **SELECT DEVICE** in the top left and choose the **MCUBOOT** USB device.
+3. Drag and drop your `app_signed.hex` file into the "File Memory Layout" section.
+4. Click **Write**. 
+5. The device is successfully flashed when the memory field turns green.
 
-Tämän jälkeen voit käyttää lisäosan "Actions"-osion "Build" -valintaa, jonka jälkeen projektikansion polkuun luodaan tarvittava .hex-tiedosto:
-```
-main_project/build/zephyr/app_signed.hex
-```
+---
 
-### Ohjelmointi
+## Open Source Resources
 
-Ohjelmointi tapahtuu nRF Connect for Desktop -sovelluksessa, josta valitaan "Programmer" (Programmer täytyy asentaa erikseen ennen sen käyttämistä painamalla "Install" "Open"-painikkeen tilalla).
+**Hardware Files:**
+* EasyEDA project & Schematics
+* Gerber files
+* Pick and Place files
+* Bill of Materials (BOM)
 
-![DesktopStart](pics/Connect_start.png)
+**Software Files:**
+* MCUboot configurations
+* Modified Arduino bootloader
+* Zephyr board files and custom examples
 
-Programmer aukeaa erilliseen ikkunaan, josta vasemmassa yläkulmassa olevasta painikkeesta "SELECT DEVICE" aukeaa lista käytettävissä olevista USB-laitteista. Näistä valitaan MCUBOOT.
+**Media & Gallery:**
+* Paper prototype concepts
+* V1 (Yellow) & V2 (Black/Blue) prototype pictures
+* "Finished" product glamour shots
+* Eye LED tests and IMU I2C logic analyzer debug screenshots
+* The "Army" (Multiple assembled devices together)
 
-![Select](pics/programmer_not_chosen.png)
-
-Laitteen valinnan jälkeen aukeaa uusi ikkuna, josta löytyy lista vaihtoehtoja. Tämän jälkeen voit navigoida app_signed.hex-tiedostoon painamalla "Add File" -painiketta. Vaihtoehtoisesti tiedoston voi vetää ja pudottaa "File Memory Layout" -kenttään.
-
-![Selected](pics/programmer_chosen.png)
-
-Kun tiedosto on lisätty ohjelmointityökaluun, vihreä alue ilmestyy "File Memory Layout" -kenttään visualisoimaan sovelluksen aloitusosoitetta ja sovelluksen kokoa verrattuna käytettävissä olevaan muistiin.
-
-![Hex](pics/programmer_hex.png)
-
-Tämän jälkeen on mahdollista ohjelmoida laite painamalla "Write" -painiketta.
-
-![Program](pics/programmer_program.png)
-
-Uudessa ikkunassa voit painaa taas "Write".
-
-Jos laite ohjelmoitiin onnistuneesti, oranssin kentän tilalle ilmestyy vihreä kenttä, jossa lukee "Completed successfully in X seconds."
-
-## Resurssit
-
-Tästä osiosta löydät tarvittavat kehittämiseen.
-
-Suositellut nRF lisäosat VS Codeen (nRF Terminal vanhentunut): <br>
-
-![Ext](pics/ext.png)
-- nRF Connect for Desktop:
-
-https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop
-
-- nRF Command Line Tools:
-
-https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools/Download?lang=en#infotabs
-
-
-- Kconfig-komennot (pjr.conf):
-
-https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/kconfig/ (Offline 18/6/2024) <br>
-https://docs.zephyrproject.org/latest/kconfig.html (Backup)
-
-- Dokumentaatiot:
-
-https://docs.nordicsemi.com/category/nrf52840-category (nRF52840) <br>
-https://invensense.tdk.com/wp-content/uploads/2016/10/DS-000176-ICM-20602-v1.0.pdf (ICM-20602 kiihtyvyysanturi) <br>
-https://docs.zephyrproject.org/latest/index.html (Zephyr project) <br>
-
-
-- EasyEDA:
-
-Projektin kytkentäkaaviot sekä linkki projektin EasyEDA sivulle löytyy tämän Git-repon kansiosta Hardware/Prototype2
+---