more project readme changes

code/project/README.md

@@ -1,5 +1,5 @@
 # micro-tuner
-An instrument tuner assistant, buit to be run on the Microbit V2. Portable and Practical!
+An instrument tuner assistant, built to be run on the Microbit V2. Portable and Practical!
 ## Background
 Selecting a project for this course was itself small challenge and lead to a slightly later start then I would have otherwise planned. 
 ### Alternatives
@@ -18,14 +18,14 @@ I chose to create an instrument tuner device with my microbit-v2 from the previo
 
 ## Goals
 ### Primary Goals (MVP)
-* The microbit shall be able to play any reference note. The reference note will be displayed on the LED matrix, and the touch button shall play the note when touched. The A and B buttons will allow the choosing of different reference notes.
+* The microbit shall be able to play any reference note (tone mode). The reference note will be displayed on the LED matrix, and the touch button shall play the note when touched. The A and B buttons will allow the choosing of different reference notes.
-* In an alternative mode, the microbit shall be able to identify the note heard by the microphone. Likewise, this note should also be displayed
+* In an alternative mode (listen mode), the microbit shall be able to identify the note heard by the microphone. Likewise, this note should also be displayed
 * Portable / can run on a battery (this should just work) 
 
 ### Stretch Goals
-* In the identify mode, if the note heard is close to a reference note, some feedback should be given (up or down arrow, etc.)
+* In the listen mode, if the note heard is close to a reference note, some feedback should be given (up or down arrow, etc.)
   * Building on the above point to set a "target" note and provide appropriate feedback
-* Avoid whatever sound+music abstraction the microbit package provides and build/interpret my own frequencies
+* Avoid to some extent, sound abstraction the microbit package provides and build/interpret my own frequencies
 
 
 ### Fun ideas (Stretch ++)
@@ -38,13 +38,34 @@ I chose to create an instrument tuner device with my microbit-v2 from the previo
 
 
 ## Source Code Overview
-Although I already have experience interfacing with the various capabilities of this device with rust, I decided to go with python for this project. I want to compare the experience of both, and also have the ability to take advantage of more abstractions if I choose to. 
+Although I already have experience interfacing with the various capabilities of this device with rust, I initially decided to go with python for this project. I want to compare the experience of both, and also have the ability to take advantage of more abstractions if I choose to. However, after making significant progress building tone mode in `micropy`, I came to find that micropy (and the microbit package) do not generally allow API access to the raw data samples of the microphone pins. They only seem to expose 256 values of sound intensity. This makes rust appear much more feasible for listen mode, and the scope of this project has changed to now implement only tone mode in python, and listen mode in rust.
 
-### [`main.py`](main.py)
+It should also be possible to flash a python application with some compiled rust, using a package like `PyO3`. If I have time, I will look into that. 
-TODO
 
 
-## Building/ Running
+### Python
+#### [`main.py`](main.py)
+This application (tone mode) works relatively well. Ultimetly, I decided to rely on microbits `music.play()` function which takes a note name as a parameter. In this regard much of the sound theory efforts are abstracted away, and there was more focus on the music and computers. The application works as follow
+
+* On start, note A4 / Midi key 69 is selected.
+* Pressing A selects the next note down; Pressing B selects the next note up
+* The selected note and octave will wrap around on both ends (0 and 128)
+* The root note (letter portion) is always rendered using all pixels except the last column
+* If a flat note is selected, the bottom pixel of the last column is dimly lit.
+* The current octave is expressed in a little-endian binary fashion with 4 pixels, top-down in the last column (not to conflict with the flat flag)
+* Pressing A and B together was intended to switch to and from listen mode (not implemented as explained above)
+### Rust
+#### [`src/main.rs`](./src/main.rs)
+
+Much of the code for this feature has beeen written, but some critical pieces remain. Some repositories were consulted, including
+
+* [`mb2-template`](https://github.com/pdx-cs-rust-embedded/mb2-template): Configurations and common packages
+* [`microbit-spectrum`](https://github.com/BartMassey/microbit-spectrum/blob/main/src/main.rs): This seems to be one of the only code examples of grabbing raw audio samples with the microbit microphone in rust
+
+
+
+
+## Building/ Running - Python
 It seems that many python microbit developers use a highly abstracted web-based IDE. I attempted to avoid that. These methods are tested only on my local debian-based linux machine, so your results may vary
 ### Dependencies
 ```bash
@@ -54,7 +75,7 @@ pip install uflash
 ### IDE support
 The microbit package does not seem to include the necessary stubs/tooltips for graceful IDE development. I found the [micro:bit Python](https://marketplace.visualstudio.com/items?itemName=MAKinteract.micro-bit-python) VS Code extension helpful. Follow its instructions
 
-###
+### Flashing
 ```bash
 uflash main.py # Optional paramter for device port like /dev/ttyACM0 if not found automatically
 ```
@@ -63,13 +84,35 @@ uflash main.py # Optional paramter for device port like /dev/ttyACM0 if not foun
 ```bash
 screen /dev/ttyACM0 115200 # You may have a different port
 ```
-## Testing
-TODO
 
-### Coded Unit tests
+## Building/ Running - Rust
-TODO
+
+### Dependencies
+
+```bash
+rustup target add thumbv7em-none-eabihf
+rustup component add llvm-tools
+cargo install cargo-binutils
+cargo install probe-run
+cargo install cargo-embed
+```
+
+### Flashing
+```bash
+cargo embed --release
+```
+
+## Testing
+More time should be allocated to write tests, as well as perform user acceptence testing
 
 ## Demo
-TODO
+
+### Tone Mode
+
+[tone-demo.mkv](./tone-demo.mkv)
+
+### Listen Mode
+
+Not Yet Ready
 
 ###### Author: David Westgate 

code/project/SETUP.md

@@ -1,8 +0,0 @@
-```
-rustup target add thumbv7em-none-eabihf
-rustup component add llvm-tools
-cargo install cargo-binutils
-cargo install probe-run
-cargo install cargo-embed
-```
-