Added documentation

README.md

 # handi-jk
 
-
-
-## Getting started
-
-## Description
-
-## Installation
-
-## Usage
-
-## Authors and acknowledgment
-
-## License
-
-## Project status
+HanDi, the Hand-cranked Display, is an electric device meant to be installed next to  the doors of lecture or meeting rooms and show their occupation.
+It includes a hand-crank generator that allows it to be energy-self-sufficient.
+It fetches the data to display via wifi.
+
+This repository contains all source files necessary to build a functioning prototype:
+- [CAD files](cad/) for 3D-printing the casing and hand crank
+- [Schematic and PCB design](pcb-lic/) for the electronic hardware
+- [Software](software/) for the [microcontroller](software/handi_esp32c3/) (ESP32-C3) and an [exemplary server](software/server/) providing schedule data
+
+Additionally to the parts built from these resources and the electronic components used for populating the PCB, you will need:
+- An e-paper display. The prototype uses the _Waveshare 7.5 inch V2 display_.
+- A stepper motor. The prototype uses the _Sanyo Denki SM2561C20B41_.
\ No newline at end of file

cad/README.md

+# Installation
+
+The CAD is done using _OpenSCAD_ and the [BOSL2](https://github.com/revarbat/BOSL2) library.
+
+# Usage
+
+The project includes CAD files for the [main box including an inlay for holding the PCB](box.scad), the [hand crank](crank.scad), and a [mount for attaching HanDi to a wall](wallmount.scad).
+
+[assembly.scad](assembly.scad) shows how the pieces are to be put together and may serve as an easy starting point for exporting the parts for slicing and printing.
+
+The project utilizes _threaded inserts_, i.e. threaded metal parts that are set into the printed parts using a soldering iron. Most locations and the corresponding sizes to be used are disclosed by the `insert_hole` keyword in the CAD files. This applies for
+- bolting the PCB to the box inlay,
+- bolting the box inlay to the box, and
+- bolting the box to the wallmount.
+
+Additionally, a threaded insert is used on the hand crank in order to bolt the handle 
+to the base.

pcb-lic/README.md

+# Installation
+
+Schematic and PCB design for this project are done in _KiCad_. The project includes several custom parts and footprints that are included in the [libs](libs/) directory.
+
+# Usage
+
+HanDi utilizes a single PCB that handles rectification, logics processing, and driving the e-paper display. It is a 2-layer board with ground pours and holes for mounting it to the box inlay.
+
+Most parts are standard components that should be widely available and can be easily switched if a specific model goes out of stock. Energy is stored using a lithium-ion capacitor. The value of this part can therefore be chosen as suitable and available.
\ No newline at end of file

software/README.md

+The software for the HanDi-project includes the [main application running on the ESP32-C3](handi_esp32c3/), an [exemplary server](server/) providing schedule data, and a [test program](esp32c3-test-pins/) for checking if the ESP32-C3 has been soldered correctly.
\ No newline at end of file

software/esp32c3-test-pins/README.md

+As this auxiliary program uses _ESP-IDF_ just as the main microcontroller software, please refer to the [instructions given there](../handi_esp32c3/) for installation, flashing and monitoring.
+
+This program simply pulls the pins of the ESP32-C3 high and low one after another and prints the steps on stdout (to be monitored via UART). Measuring the voltage levels on the PCB allows for checking if all pins got properly connected during the soldering process. This is a helpful check as it proved difficult achieving perfect connections (i.e. connecting all pins between chip and PCB, and not connecting multiple pins to each other) when reflow-soldering the bottom pins of the ESP32-C3 mini module.
\ No newline at end of file

software/handi_esp32c3/README.md

+# Installation
+
+This software is meant for running on an _ESP32-C3_ microcontroller and makes use of the _ESP-IDF_.
+
+# Usage
+
+## Customization
+
+The software takes care of multiple tasks necessary for HanDi's operation:
+- State-of-charge assessment
+- WiFi updates
+- Feedback during charging
+- Prevention of overcharging
+- Halt regular operation on low energy
+
+These tasks rely on several constants such as WiFi authentication data and the size of the lithium-ion capacitor. The most important of these (that are prone to differ between setups) can be set using the ESP-IDF `menuconfig` tool (run `idf.py menuconfig` inside this directory).
+
+Others (for which the standard values might very well suit you) can be found as macros in the source files. Adjusting the macros allows for detailed changes such as setting the number of bars used for showing the state of charge.
+
+## Flashing
+
+Bringing the software to the ESP32-C3 is done via UART. Therefore, you need to connect a USB-to-UART bridge to your computer, and connect Rx and Tx of the USB-to-UART bridge to the respective opposites on the PCB. Additionally, connect the ground of the USB-to-UART bridge to the ground of the PCB.
+
+Then you boot the device into download mode by pressing and holding the FLASH1 and FLASH2 buttons, additionally pressing and releasing the RESET button, and finally releasing the FLASH1 and FLASH2 buttons.
+
+Finally, you build the project, flash the built files to the ESP32-C3, and monitor its console output for debugging purposes by executing `idf.py -p <uart-device> build flash monitor` where `uart-device` is most likely something like `/dev/ttyUSB0`. The `monitor` part of this command is optional and requires restarting the ESP32-C3 (by pressing the RESET button) after flashing is done.

software/server/README.md

+# Installation
+
+This server is based on Python3 and the `flask` framework. It additionally uses `pillow` for generating and maniuplating images.
+
+The project includes a [requirements file](requirements.txt) that can be used to install all required Python3 packages. This is best done in a virtual environment:
+
+- Create the environment in the directory _env_ in this directory: `virtualenv env`
+- Activate the environment: `source env/bin/activate`
+- Install the dependencies: `python3 -m pip install -r requirements.txt`
+
+# Usage
+
+## Adjusting to your needs
+
+In its current state, this server generates mock images displaying made up schedules. This is meant for testing but can also serve as a basis for actual production systems. While the entries of the schedule are made up, the process of transferring them into an image and sending it is independent. Since it automatically scales and adjusts the contents according to the content of the entries and the available space, it is a mighty tool.
+
+In order to switch the randomly generated schedule for an actual one, you only have to change the according line in [app.py](app.py) (`entries = schedule_random()`) in the `schedimg` route (and providing the actual schedule instead).
+
+If you use a different display size or fragmentation than set as default in the ESP32-C3 software, you will also have to adjust the size of the image generated by the server. You can do this by altering `DEFAULT_WIDTH` and `DEFAULT_HEIGHT` in [settings.py](settings.py).
+
+## Running
+
+Note: If you installed the dependencies in a virtual environment as suggested above, please remember to always activate the latter before proceeding.
+
+Running the server is as simple as running [app.py](app.py), i.e. `./app.py` or `python3 app.py`
\ No newline at end of file

software/server/requirements.txt

+click==8.1.3
+Flask==2.2.2
+itsdangerous==2.1.2
+Jinja2==3.1.2
+MarkupSafe==2.1.2
+Pillow==9.4.0
+Werkzeug==2.2.2