From 3472e4125c1cf348d67f5231b0205fa081b5fa89 Mon Sep 17 00:00:00 2001
From: Vova Lando <vova.lando@gmail.com>
Date: Fri, 4 Oct 2024 00:32:32 +0300
Subject: [PATCH] fix: updated docs structure, included some flashing manuals

---
 Readme.md             | 16 +++++++++----
 electronics/Readme.md | 10 +++++++++
 firmware/Readme.md    | 11 +++++++++
 software/Readme.md    | 52 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 85 insertions(+), 4 deletions(-)
 create mode 100644 electronics/Readme.md
 create mode 100644 firmware/Readme.md
 create mode 100644 software/Readme.md

diff --git a/Readme.md b/Readme.md
index dcc69c0..d8a8bc7 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,12 +1,20 @@
+
 # Pilkki
 SWD flashing tool for EFM32 microcontrollers.
 
 ## Project structure
 
-Utility to interact with flasher could be found in [software](software) folder.
+The project is divided into three parts:
+
+1. **[Software](software)**: The flashing utility.
+2. **[Electronics](electronics)**: Schematics and PCB (KiCAD).
+3. **[Firmware](firmware)**: Firmware for the target device.
+
+### How to Use
 
-To use flasher, call `cargo run`, or build by `cargo build --release`
+To use the flasher, you can either:
 
-Schematics and PCB (KiCAD) are in [electronics](electronics) folder.
+- Run the utility directly with `cargo run`
+- Build the project in release mode with `cargo build --release`
 
-Firmware sources are [here](firmware)
+More info on how to use pilkki in [Readme.md](software/Readme.md) in the [Software](software) section
\ No newline at end of file
diff --git a/electronics/Readme.md b/electronics/Readme.md
new file mode 100644
index 0000000..b27ea91
--- /dev/null
+++ b/electronics/Readme.md
@@ -0,0 +1,10 @@
+# Pilkki Electronics
+This folder contains the schematics and PCB layout for the Pilkki, created in KiCad.
+
+### Files
+
+- `pilkki.kicad_pcb`: The PCB layout.
+- `pilkki.kicad_sch`: The circuit schematics.
+- `pilkki.kicad_pro`: The KiCad project file.
+
+To view and edit these files, use [KiCad](https://kicad.org/).
diff --git a/firmware/Readme.md b/firmware/Readme.md
new file mode 100644
index 0000000..a4b1d03
--- /dev/null
+++ b/firmware/Readme.md
@@ -0,0 +1,11 @@
+# Pilkki Firmware
+This folder contains the source code for the firmware that runs on Pilkki.
+
+### Structure
+
+- `app/`: Application code for the firmware.
+- `common/`: Common utility functions.
+- `drivers/`: Device drivers.
+- `targets/`: Target-specific code.
+
+Build instructions can be found in the respective submodules.
diff --git a/software/Readme.md b/software/Readme.md
new file mode 100644
index 0000000..a4959c2
--- /dev/null
+++ b/software/Readme.md
@@ -0,0 +1,52 @@
+
+# Pilkki Software
+This folder contains the utility to interact with the flasher.
+
+## How to Use
+
+To run the flashing tool:
+- Use `cargo run` to run the tool.
+- Use `cargo build --release` to build the release version.
+
+The utility should automatically detect the connected port; otherwise, you can specify it manually with the `--port` flag.
+
+### Getting help
+```sh
+cargo run -- help
+```
+
+### Finding the Port to Which Your Device Is Connected:
+
+**Linux:**
+```sh
+ls /dev/ttyUSB*
+```
+
+**MacOS:**
+```sh    
+ls /dev/tty.* /dev/cu.*
+```
+
+### Verify Connection to the Device
+
+To connect to the device, run:
+```sh
+cargo run -- --port /port/address connect
+```
+
+### Flash a New Binary:
+
+To flash a new binary to the device:
+```sh
+cargo run -- write --input /path/to/your/binary.bin
+```
+Or, if you need to specify the port manually:
+```sh
+cargo run -- write --port /port/address --input /path/to/your/binary.bin
+```
+
+### Getting the Firmware Binary
+
+You can either:
+- Build the binary using the code from the [kampela-firmware](https://github.com/Kalapaja/kampela-firmware) repository.
+- Download the compiled binary from the [releases](https://github.com/Kalapaja/kampela-firmware/releases) section.