Merge pull request #20 from StrijpT-Ellie/feat/documentation

Feat/documentation

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contibuting to ContourWall
+
+This page is for people who are interested in contributing to the Contour Wall project by work such as code or documentation. If you have anything outside that or you have a problem
+, read [Contributing in different ways](#Contributing-in-different-ways).
+
+## Contributing to CDI
+
+When you are missing a feature in CDI (**C**ontourwall **D**isplay **I**nterface) or can something be improved, it is best to create a Github issue first. This way is can be discussed first before time is invested.
+
+Updating CDI can be quite the undertaking, the firmware, core library, documentation and more needs to be updated. Maybe even all the wrappers if it is a really significant change. We also like to keep it as minimal as possible. Therefore we like to discuss before we implement.
+
+However, if you are ready to implement your change, make sure you have a good understanding of [UART](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter), our [firmware](firmware/firmware.ino) and the [core libary](lib/cw-core/). CDI is explained and defined in the [software architecture document](docs/software_architecture/ELLIE_software_achitecture.pdf) could also help.
+
+## Contributing to the core libary
+
+Have you found a bug, optimization or do you want to implement a feature for the core libary. Make sure that you understand the whole architecture of the system, refer to the [architecture document](docs/software_architecture/ELLIE_software_achitecture.pdf) for better understanding of the whole system. Also, if you are planning on the part of the library which implements CDI, it is also recommended to have a basic understanding of [UART](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter).  
+
+
+
+## Contributing to (new) wrappers
+
+Do you want to use a language in which there is not a wrapper available? Make sure that you understand the core libaries API very well, also refer to the [architecture document](docs/software_architecture/ELLIE_software_achitecture.pdf) for better understanding of the whole system.
+
+Refer to the [ContourWallCore documentation](/lib/cw-core/README.md#how-to-use) to see how to compile the libary to a `*.dll` or `*.so`. When implementing your own wrapper in a new language, try to mimic the implementation of the [Python](lib/wrappers/python/) or [Rust](lib/wrappers/rust/) wrapper.
+
+If you think that others would like to use your wrapper, you can create a pull request. Your code will be reviewed and if good enough it will be merged into the main branch. Before you make a pull request there are a couple of things you need to check to smooth out the reviewing process. We want to make sure that all wrappers are up to standard, therefore we have number of "rules" and conventions:
+
+1. **Contain as little logic as possible.** If all the wrappers have the same logic, it should be considered to move this logic into the core library in Rust.
+2. **Follow existing conventions of packages often used in combination with the wrapper.** This reduces the complexity of incorporating the Contour Wall into existing projects. E.G. OpenCV will be used to display content on the ContourWall, make sure that the wrapper uses OpenCV conventions. This makes sure that little conversions between data structures is needed to improve performance and reduce complexity.
+3. **Keep the API of the wrappers similar.** When the API of all wrappers is identical is it easy to switch between them, streamlines wrapper development and reduces the learning curve.
+4. **API documentation**. There is in-code documentation of the API of your wrapper.
+5. **Getting started**. To instruct other on how to use your libary. We would like to see a getting started, this includes instructions on how to set everything up and a small code sample.
+
+Are you unsure if your wrapper checks all the boxes? Just create a pull-request, we can always help!
+
+## Contributing to the firmware
+
+TODO
+
+## Contributing to documentation
+
+If you find a place where documentation is lacking create a issue, or create a pull request with the new or improved documentation.
+
+## Contributing in different ways
+
+Create an issue on Github or contact <[email protected]>

PCB/README.md

@@ -1,34 +1,17 @@
-# ELLIE Panel PCB
+# PCB's readers guide
 
 > **DO NOT RELOCATED THIS PAGE TO A DIFFERENT URL, A QR CODE ON THE PCB POINTS TO THIS**
 
-All files to order more PCB's can be found in this directory. Ordered and assembled from JLCPCB with LCSC as part supplier.
+All files to order more PCB's can be found in this directory. Ordered and assembled from [JLCPCB](https://jlcpcb.com/) with [LCSC](https://www.lcsc.com/) as part supplier. The CAD software used to design the PCB's is [EasyEDA](https://easyeda.com/). These three companies and tools are well integrated and therefore the design process is easier.
 
-# Tech spec & info
+## Display panel
 
-- **LED type:** WS2812B ([datasheet](https://cdn-shop.adafruit.com/datasheets/WS2812B.pdf))
-  - **Total current:** 60mA * 25 = 1500mA. However, in reality, one full-white WS2812B LED only uses 36mA. Therefore one board uses about 900mA.
-- **Dimensions (WxH):** 220mm x 220mm (30mm space between the PCB's)
-- **Mounting hole grid size:** 125mm
-- **Mounting hole size:** 3mm
-- **Decoupling capacitor**: 100nF
-- **Big Capacitor:** 1000uF capacitor pin holes (Not placed be default, solder by hand if needed.)
-- **Coppper Thickness:** 1oz Copper layer
-- **Trace Width:** 5v trace has 7.5mm width. Can handle max of 10A
-- **Assembled PCB Weigth:** ~180 grams (Including all SMD components)
+For information about the Display Panels go to [display_panel/](/display_panel/). Here you can find schematics, dimensions and general information about the PCB. Here you will also find information about ordering the PCB van JLCPCB.
 
-# Dimensions
+## ESP32S3 Breakoutboard
 
-> NOTE: Dimensions image is not to scale
+For information about the Display Panels go to [esp32s3_breakoutboard/](/esp32s3_breakoutboard/). Here you can find schematics, dimensions and general information about the PCB. Here you will also find information about ordering the PCB van JLCPCB.
 
-![dimensions](img/pcb_dimensions.png)
+## Usefull links
 
-# Electrical Schematic
-
-![schematic](img/Schematic_ELLIE_DISPLAY_PANEL.png)
-
-# PCB
-
-Front of PCB                | Back of PCB
---------------------------- | -------------------------
-![pcb_front](img/front.png) | ![pcb_back](img/back.png)
+- **How do I order from JLCPCB:** [https://jlcpcb.com/help/article/54-how-do-i-place-an-order](https://jlcpcb.com/help/article/54-how-do-i-place-an-order)

PCB/display_panel/README.md

@@ -0,0 +1,44 @@
+# ELLIE Display Panel 
+
+The "Display Panel" PCB's are the panels with a 5x5 LED grid, spaced at 5cm. 
+
+## PCB renders
+
+Front of PCB                | Back of PCB
+--------------------------- | -------------------------
+![pcb_front](img/front.png) | ![pcb_back](img/back.png)
+
+## Ordering information
+
+Got to [this image](img/order_settings.png) for information about what settings are recommended when ordering the display panels. 
+
+It is also not recommeneded **NOT** to place the 330 ohm resistor ([BOM settings for reference](img/ordering_BOM.png)) on the `DI` trace. This resistor should only be placed at the beginning of the chain of WS2812B LED's. See image below for context:
+
+<img src="img/330ohm_resistor.png" alt="drawing" width="400"/>
+
+## Specification & infomation
+
+- **LED type:** WS2812B ([datasheet](https://cdn-shop.adafruit.com/datasheets/WS2812B.pdf))
+  - **Total current:** 60mA * 25 = 1500mA. However, in reality, one full-white WS2812B LED only uses 36mA. Therefore one board uses about 900mA.
+- **Dimensions (WxH):** 220mm x 220mm (30mm space between the PCB's)
+- **Mounting hole grid size:** 125mm
+- **Mounting hole size:** 3mm
+- **Decoupling capacitor**: 100nF
+- **Big Capacitor:** 1000uF capacitor pin holes (Not placed be default, solder by hand if needed.)
+- **Coppper Thickness:** 1oz Copper layer
+- **Trace Width:** 5v trace has 7.5mm width. Can handle max of 10A
+- **Assembled PCB Weigth:** ~180 grams (Including all SMD components)
+
+## Dimensions
+
+There are four additional 3mm screw holes on the each PCB, one close to each "main" screw holes. "Main" screw holes have thicker rings printed around them, "extra" screw holes have thinner ones. The extra screw holes is if the holes no the wooden tiles do not align with the holes on the panels; you have additional.
+
+These additional screw holes are not drawn on the dimension diagram below.
+
+> NOTE: Dimensions image is not to scale
+
+![dimensions](img/dimensions.png)
+
+## Electrical Schematic
+
+![schematic](img/Schematic_ELLIE_DISPLAY_PANEL.png)

PCB/esp32s3_breakoutboard/README.md

@@ -0,0 +1,23 @@
+# ELLIE ESP32-S3 Breakoutboard
+
+The "ESP32-S3 Breakoutboar" PCB's are ESP32-S3 breakoutboards. These boards to already exist but these custom ones have two main advantages over the "generic" ones:
+
+1. These come with additional holes spaced at 1 mil or 2.56 mm, in these holes screw terminals can be soldered, aiding the ease of construction and maintainance of the Contour Wall.
+2. Having a smaller footprint. The generic ones have a larger footprint, which would not fit in the electrical boxes.
+
+## PCB renders
+
+Front of PCB                | Back of PCB
+--------------------------- | -------------------------
+![pcb_front](img/front.png)      | ![pcb_back](img/back.png)
+
+## Specification & infomation
+
+- **Made for:** [ESP32-S3 DevKitC](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/hw-reference/esp32s3/user-guide-devkitc-1.html)
+- **Dimensions:** 45mm x 70mm
+- **Mounting hole size:** 3mm
+- **Coppper Thickness:** 1oz Copper layer
+
+## Electrical Schematic
+
+![schematic](img/Schematic_ELLIE_BREAKOUTBOARD_ESP32S3.png)

README.md

@@ -8,15 +8,29 @@ This repository contains: research, designs, source code and documention of the
 
 ![ellie_tq_render](/img/ellie_tq_denoise.png)
 
+## Documentation readers guide
+
+- [You want to use the Contour Wall for your project](docs/getting_started.md)
+- [You need to know something about the construction](docs/construction/)
+- [(TODO) You have bug, problem or suggestion]()
+- [You need to know something about the software architecture](/docs/software_architecture/ELLIE_software_achitecture.pdf)
+- [You need to know something about the hardware architecture documents (Excl. PCB's) ](/docs/hardware_architecture/README.md)
+- [You need to know something about the PCB's designs, information or files](/PCB/)
+- [You want to write an additional wrapper](CONTRIBUTING.md#contributing-to-new-wrappers)
+- [You want to contribute to the core libary](CONTRIBUTING.md#contributing-to-the-core-libary)
+- [(TODO) You want to contribute to the ESP32-S3 firmware](CONTRIBUTING.md#contributing-to-the-firmware)
+- [You want to contribute to CDI](CONTRIBUTING.md#contributing-to-cdi)
+
 ## Directory Structure
 
-- `pcb/`: Information and design of the PCB's, such as: dimensions, electrical properties. All the design files of the PCB are also in there.
+- `docs/`: Additional documentation that does not belong to specific parts (E.G. architecture or how-to)
 - `firmware/`: The firmware for the tiles, running on ESP32's. Implements protocol and controls PCB's.
 - `font/`: A custom low-res font for the Contour Wall, including util functions
-- `img/`: Images used in the repository
+- `img/`: images for E.G. README's 
 - `lib/`: The library to control the Contour Wall
+- `pcb/`: Information and design of the PCB's, such as: dimensions, electrical properties. All the design files of the PCB are also in there.
 - `research/`: All the research scripts, mostly regarding contour extraction from video feed.
-- `scripts/`: Extra script for a variety of use cases
+- `scripts/`: Additional scripts for E.G. a pipeline or development.
 
 ## Contributors
 

docs/construction/README.md

@@ -0,0 +1,4 @@
+# Construction documentation
+
+- [(TODO) If you need to know about (dis)assembly of the Contour Wall](wall_assembly/)
+- [If you need to know how a tile is made](tile_technical_drawings/)

docs/construction/wall_assembly/README.md

@@ -0,0 +1,3 @@
+# Assembly guide
+
+TODO

docs/getting_started.md

@@ -0,0 +1,5 @@
+# Getting started
+
+If you want to incorperate the Contour Wall into your project you are going to have to decide on the language that you want to use. Currently, the two languages in which the library to control the wall is implemented are: Python and Rust. If you want to use a different language you are going to have to [implement it yourself](../CONTRIBUTING.md#contributing-to-new-wrappers).
+
+The documentation for the for the library that you are going to use can be found in their respective directory, which are all located in the [`wrappers/`](../lib/wrappers/) directory. All wrappers should have examples are guides on how to setup your development enviroment.

lib/cw-core/README.md

@@ -0,0 +1,11 @@
+## Contour Wall Core
+
+This is the "core" library of the Contour Wall. It provides a low-level interface to control the Contour Wall. It is not meant for developers to use directly, other languages should have wrappers implemented around this library. Those wrappers should be used by developers to control the Contour Wall.
+
+To see where this library sits in the Contour Wall system, refer to the [software architecture](../../docs/software_architecture/ELLIE_software_achitecture.pdf). If you want API level documentation run: `cargo doc --open` or go to <https://docs.rs/contourwall_core/latest/contourwall_core/>.
+
+## How to use
+
+If you are planning on using this library in another Rust project, run this command in your project: `cargo add contourwall_core`.
+
+If you are planning on using it in another language you need to compile it to a `*.so` (for Unix) or `*.dll` (for Windows). Execute: `cargo build --release`. Then, in the directory `target/release` you will find a file which is called `contourwall_core.dll` or `contourwall_core.so`.

lib/wrappers/python/README.md

@@ -2,13 +2,43 @@
 
 ## How to run
 
-1. Install Python, version 3.9 to 3.11
+1. Install Python, version >3.9
 2. Install Cargo
 3. Install modules: `python3 -m pip install -r requirements.txt`
 4. Compile core library located at `contourwall/lib/cw_core`: `cargo build --release`
 5. Move compiled library located in `target/release` directory to same directory as `contourwall.py`
 6. Run: `python3 demo.py`
 
+## Example Usage
+Create a new file and use the import 'from contourwall import ContourWall, hsv_to_rgb', to be able to use the python wrapper.
+
+To utilize this library, ensure you have the necessary serial port permissions and ESP32 firmware flashed with the ContourWall protocol support.
+
+``` Python
+from contourwall import ContourWall, hsv_to_rgb
+
+cw = ContourWall()
+cw.single_new_with_port("COM3")
+
+for i in range(0, 360):
+    cw.pixels[:] =  hsv_to_rgb(i, 100, 100)
+    cw.show()
+cw.fill_solid(0, 0, 0)
+cw.show()
+```
+
+## Functions in the python wrapper
+|Type|Classes & Functions|Description|
+|---|---|---|
+|class|`ContourWall`|When this class is called it will be initiated by the `__init__` function.|
+|def|`__init__`|This function is used to create an instance of the `ContourWall` class.|
+|def|`new`|This function is used to create the `ContourWallCore` object when the COM ports are unknown.|
+|def|`new_with_ports`|This function is used to create a new instance of `ContourWallCore` when the COM ports are known.|
+|def|`single_new_with_ports`|This function is used to create a new instance of ContourWallCore when a single COM port is known.|
+|def|`show`|This function is used to show the current state of the pixel array on the ContourWall.|
+|def|`fill_solid`|This function is used to fill the entire ContourWall with one single color.|
+|def|`hsv_to_rgb`|This function is used to convert HSV color code to RGB color code.|
+
 ## Running MyPy typechecker
 
-- `python3 -m mypy contourwall.py --disallow-untyped-defs`
+- `python3 -m mypy contourwall.py --disallow-untyped-defs`