Merge pull request #4 from Vovke/pilkki-readme-update

rewritten flasher utility readme, added macos steps

software/Readme.md

@@ -1,142 +1,110 @@
-# Flasher
-## Utility for flashing
+Pilkki - Flasher Utility
+===============
 
-TODO: description
+Description
+-----------
 
-## Build
+TODO: Add a detailed description of the Flasher utility.
 
-You will need Linux (tested on ArchLinux), CMake, libudev, ninja and c++ compiler.
+Prerequisites
+-------------
 
-Clone this repository with submodules:
-```sh
-git clone --recurse-submodules https://github.com/Kalapaja/Pilkki
-```
+### For Linux
 
-Build code:
-```sh
-mkdir build
-cd build
-cmake .. -G Ninja
-ninja
-```
+*   CMake
+*   Ninja
+*   C++ Compiler
+*   libudev
 
-## Install
-```sh
-[sudo] ninja install
-```
+#### Installing Dependencies on Ubuntu
 
-### Install in Ubuntu
-```
-sudo apt install ninja-build libudev-dev
-cd ./software
-cmake . -G Ninja
-sudo ninja install
+Specifically for Ubuntu (probably relevant for most debian distro), install the required packages:
 
-pilkki -v
-> Pilkki (ver. 0.0.1)
-```
-## Usage
-
-Help message contains comprehensive information about usage:
 ```sh
-pilkki --help
-```
-You should get output like this:
+sudo apt install ninja-build libudev-dev
 ```
-Pilkki - SWD Flasher
-
-All the following arguments require connection to the hardware part of the SWD flasher
-The address and size can be specified in either decimal or hexadecimal format (prefixed with 0x).
-Both values must be multiples of a word (4 bytes).
-
-Usage: pilkki  [options...] [SUBCOMMAND: connect, crc, erase, halt, id, read, reset, run, write, ]
-
-Options:
-     -v,--version : Print version (of this program). [implicit: "true", default: false]
-        -?,--help : print help [implicit: "true", default: false]
-
-
-Subcommand: connect
-Connect to the target and halt it.
-Usage: connect  [options...]
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
+### For MacOS
 
+*   CMake
+*   Ninja
+*   GCC Compiler
 
-Subcommand: crc
-Calculate CRC32 checksum of memory region on the target.
-Usage: crc  [options...]
+#### Installing Dependencies on MacOS
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
-        -a,--addr : Starting address on the target. [default: 0x08000000]
-      -l,--length : Length of the memory region to read (in bytes). [default: none]
+Install the necessary tools using [Homebrew](https://brew.sh/):
 
+```sh
+brew install cmake ninja gcc
+```
 
-Subcommand: erase
-Erase firmware from the target.
-Usage: erase  [options...]
-
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
-        -a,--addr : Starting address on the target. [default: 0x08000000]
-          --pages : Number of pages to erase. [default: none]
+Building the Code
+-----------------
 
+### Cloning the Repository
 
-Subcommand: halt
-Halt the target.
-Usage: halt  [options...]
+Clone the repository with all its submodules:
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
+```sh
+git clone --recurse-submodules https://github.com/Kalapaja/Pilkki
+```
 
+### Compiling the Code
 
-Subcommand: id
-Get SWD Programmer Hardware ID.
-Usage: id  [options...]
+Navigate to the cloned directory and compile the code:
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
+```sh
+mkdir build 
+cd build 
+cmake .. -G Ninja 
+ninja
+```
 
+### Installation
 
-Subcommand: read
-Read firmware from the target.
-Usage: read  [options...]
+Install the utility:
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
-        -a,--addr : Starting address on the target. [default: 0x08000000]
-      -o,--output : Output file name: <filename>.(bin/hex) [default: out.bin]
-      -l,--length : Length of the memory region to read (in bytes). [default: none]
+```sh
+sudo ninja install
+```
 
+### Verifying Installation
 
-Subcommand: reset
-Reset the target (soft/hard).
-Usage: reset  [options...]
+To verify the installation, check the installed version:
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
-      --hw,--hard : Hard reset. [implicit: "true", default: false]
+```sh
+pilkki -v
+```
 
+The output should show `Pilkki (current version)`.
 
-Subcommand: run
-Run the target.
-Usage: run  [options...]
+Usage
+-----
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
+*   Find the port to which your device is connected:
 
+**Linux**    
+```sh
+ls /dev/ttyUSB*
+```
 
-Subcommand: write
-Write firmware to the target.
-Usage: write  [options...]
+**MacOS**    
+```sh    
+ls /dev/tty.* /dev/cu.*
+```
 
-Options:
-        -p,--port : Serial port to interact with flasher. Autodetect if not specified. [default: none]
-        -a,--addr : Starting address on the target. [default: 0x08000000]
-       -i,--input : Input file name: <file_name>.(bin/hex) [required]
-      -l,--length : Length of the memory region to write (in bytes). [default: none]
+*   Verify port by connecting to the device:
+
+```sh
+pilkki connect --port /port/address
+```
+
+*   Flash a new binary:
+
+```sh
+pilkki write --port /port/address --input /path/to/your/binary.bin
 ```
+
+### Getting Firmware Binary
 
-For more information feel free to look at source code.
+Build the binary using code in [kampela-firmware](https://github.com/Kalapaja/kampela-firmware) repo or get compiled binary from the [releases](https://github.com/Kalapaja/kampela-firmware/releases) section