Merge branch 'master' into RP2040

Documentation/Fabrication/MPRLS_pressure_sensor/README.md

@@ -0,0 +1,90 @@
+# FLipMouse MPRLS Pressure Sensor Board
+
+**Fabrication Note v1.0, AsTeRICS Foundation**
+
+![FLipMouseLogo](./img/flipmouseLogo.png)
+
+# Scope
+
+The FLipMouse uses a pressure sensor to detect any sip and puff input on the mouthpiece.
+
+Version 2 uses a MPXV7007GP pressure sensor, which provides an analog value, exactly half of the supply voltage when idle.
+
+From 2022 onwards, this sensor is getting VERY expensive (~11$ 2021; ~35$ 2022) and hard to buy (~52 weeks lead time).
+
+Version 3 of the mouse supports 2 different types of sensors:
+
+* MPXV7007GP (same sensor as in FMv2)
+* MPRLS0025PA00001A
+
+There are major differences between these two:
+
+* MPRLS uses I2C
+* MPRLS is an absolute pressure sensor, needs calibration on FM startup
+* MPRLS is not hand-solder friendly
+
+Because this sensor is basically impossible to solder with a solder iron. We still want to ship this sensor with assembled devices as well as construction kits, therefore we designed a small adapter PCB which needs to be __reflow soldered__ before further use.
+
+# Preparation
+
+## Material
+
+| Nr.  | Description              | Source                                 | Image |
+| ---- | ------------------------ | -------------------------------------- | ----- |
+| 1    | MPRLS adapter PCB        | <TBA: check in PCB to repo & add link> |       |
+| 2    | 3 parts as stated in BOM | <TBA: check in PCB to repo & add link> |       |
+
+__Note: Material will be referenced in square brackets: []__
+
+## Tools
+
+| Nr.  | Description                       | Source                                                       | Image                                             |
+| ---- | --------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- |
+| 1    | Reflow solder equipment           | Fablab, or university. You need a reflow oven, a stencil, solder paste, tweezers |                                                   |
+| 2    | Testbench for MPRLS               | <TBA: add repository link to test firmware & HW>             | ![Picture of sensor testbench](img/testbench.jpg) |
+| 3    | Permanent marker (red/blue/green) | DYI store, paper store (possibly any store)                  |                                                   |
+
+__Note: Tools will be referenced in curly brackets: {}__
+
+<div style="page-break-after: always; break-after: page;"></div>
+# Procedure
+
+__Prepare PCB:__
+
+1. Mount the stencil on your holder _{1}_
+1. Apply solder paste on PCB(s) _[1]_
+
+__Place parts: (note: guaranteed information is available in the KiCAD project, this is for reference only)__
+
+1. Place the MPRLS sensor, pin one has a small triangle _{2}_
+2. Place both capacitors (1nF / 100nF) _{2}_
+
+__Solder:__
+
+1. Follow the instructions for your reflow solder equipment to solder the PCBs
+
+__Testing:__
+
+1. This sensor can be prone to solder errors, especially if you are not experienced in reflow soldering & paste application
+2. Follow the test procedure for __EVERY__ soldered sensor PCB
+
+
+
+# Testing
+
+Sensor testing is done via the testbench for sensors, which is based on a Teensy.
+
+1. Attach the testbench to a USB port (micro USB cable)
+2. Wait for finished initialisation, `Insert device` should be shown on the display
+3. Attach each sensor under test on the left pin header (4pins): ![sensor connected on the testbench](img/sensorattached.jpg)
+4. Hold down the sensor for the test to provide sufficient contact without soldering
+5. The display should show `Found dev @0x18`, `MPRLS pressure`. __If not:__ This sensor is broken
+6. Wait for the tester to run a test cycle
+7. The display should show now: `Fin, avg.: xxx`, the actual value depends on your ambient pressure, but should be in the __range of 400-600__. __If not:__ this sensor is broken.
+8. Every character on the __second line__ should be a __`+` symbol__. __If not:__ Either there was a bad contact (press the sensor against the pins and re-run the test) or this sensor is broken (if you tried it more than once).
+9. If the test finished successfully, __mark this sensor__ with a permanent marker _{3}_.
+10. Repeat the procedure with another sensor from __step 3__.
+
+## Documentation
+
+For each produced batch, fill out one document __template_MPRLS_production.ots__ and save it as: `mprls_<date>.ods`(e.g.: mprls_20221118.ods)

Documentation/Fabrication/mouthpiece/README.md

@@ -0,0 +1,103 @@
+# FLipMouse - Mouthpiece
+
+**Fabrication Note v1.0, AsTeRICS Foundation**
+
+![FLipMouseLogo](./img/flipmouseLogo.png)
+
+# Scope
+
+The FLipMouse needs a stick in front to be actuated via finger or lip movements. From 2022 on, the AsTeRICS Foundation produces the mouthpieces in-house.
+
+Basic components of the mouthpiece are:
+
+1. Acryllic pipe, variable length
+2. Male Luer Lock adapter to M6
+3. Filter
+
+The acryllic pipe (Ø10/6mm) is glued to the Luer Lock adapter with epoxy resin.
+
+![Fully assembled mouthpiece with filter](./img/mouthpiece.png)
+
+
+
+# Preparation
+
+## Material
+
+| Nr.  | Description                                                  | Source                                                       | Image                                                        |
+| ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| 1    | Male Luer Lock to M6 adapter                                 | https://www.droh.de/produkt/2836-luer-lock-adapter-mit-m6-gewinde-mannlich | ![A male Luer Lock to M6 thread adapter](./img/maleluer.png) |
+| 2    | Female Luer Lock to pipe adapter. __Note:__ this part is either already in the holder OR it can be taken from the FLipMouse construction kit. | https://www.droh.de/produkt/1752-luer-lock-adapter-mit-m6-gewinde-fur-schlauche-mit-3-mm-id-und-zur-geratemontage-weiblich | ![A female Luer Lock to 3mm pipe adapter](./img/femaleluer.png) |
+| 3    | Acryllic pipe (Ø10/6mm)                                      | https://acrylhaus.com/Acrylglasrohr-rund-XT-transparent-R-10-6mm-Aussen-Innen-1000mm | ![Acryllic pipe, 10mm outer and 6mm inner diameter](./img/acryllic.png) |
+| 4    | Cigarette filters, 6mm diameter                              | Local tobacco store                                          | ![6mm cigarette filter](./img/filter.png)                    |
+| 5    | Epoxy resin, UHU 300 or equivalent                           | DIY-store                                                    | ![UHU epoxy](./img/epoxy.png)                                |
+
+__Note: Material will be referenced in square brackets: []__
+
+## Tools
+
+| Nr.  | Description            | Source                                 | Image                                                        |
+| ---- | ---------------------- | -------------------------------------- | ------------------------------------------------------------ |
+| 1    | Mixing pan & toothpick | Included in the epoxy kit or DIY-store | ![A analog film case with a toothpick](./img/mixingpan.png)  |
+| 2    | Miter saw              | DIY-store                              | ![Mitre saw](./img/mitresaw.jpg)                             |
+| 3    | Heat gun               | DIY-store                              | ![A heat gun in an original case with different accessories](./img/heatgun.jpg) |
+| 4    | Mouthpiece holder      | 3D printed, .stl file in this folder.  | ![Holding tool with 15 places for Luer Lock adapters and 2 holes to screw the holder to a surface](./img/holder.png) |
+| 5    | Sand paper, 240grit    | DIY-store                              |                                                              |
+
+__Note: Tools will be referenced in curly brackets: {}__
+
+<div style="page-break-after: always; break-after: page;"></div>
+# Procedure
+
+__Cut the acryllic pipe:__
+
+1. Adjust the mitre saw _{2}_ to the necessary length: 50, 100, 120 or 150mm
+2. Cut as many pipes _[3]_ as you want to produce
+3. Use the heat gun _{3}_ at **500°C** and heat up both ends for ~**5s** (removing the burr)
+
+
+
+__Prepare holder and epoxy resin:__
+
+1. Place as many female luer lock adapters _[2]_ in the holder _{4}_ as you want to produce. Take care that both hex nuts are in the holder.
+2. Attach a male luer lock adapter _[1]_ on each female adapter by pushing and turning 180°.
+3. Mix epoxy resin 50:50 in the mixing pan (TBA: give here a weight for a full holder)
+
+
+
+__Glueing:__
+
+1. Use the toothpick to apply epoxy resin on the male luer lock's _[1]_ M6 thread. __Note:__ do NOT apply too much and start applying directly on the thread.
+2. Push the acryllic pipe _[3]_ on the luer lock adapter _[1]_. __Note:__ make sure you have clean hands.
+3. Repeat for all luer lock adapters
+4. Use paper or a tissue to remove any surplus epoxy.
+
+
+
+`Wait for 12h`
+
+
+
+__Finalize:__
+
+1. Us the sand paper _{5}_ to make a 45° / 1mm chamfer on the outside of the mouthpiece; remove any burr inside the acryllic pipe (either with sand paper, a big drill with ~10mm or a countersunk head)
+1. Use the heat gun _{3}_ at ~500°C and heat up the top for ~5 to have rounded edges
+2. Put a filter _[4]_ into the acryllic pipe
+3. TBA: how to mark the mouthpieces with a chargenumber?
+4. Unscrew the luer locks, the female luer lock can be put into the construction kit.
+
+
+
+# Testing
+
+## Tools
+
+<TBA, use a strain gauge setup>
+
+## Procedure
+
+<TBA, use a strain gauge setup>
+
+## Documentation
+
+For each produced batch, fill out one document __template_mouthpiece_production.ots__ and save it as: `mouthpiece_production_<date>.ods`(e.g.: mouthpiece_production_20221118.ods)

Documentation/Fabrication/rp2040_preparation/README.md

@@ -0,0 +1,90 @@
+# FLipMouse/Pad Arduino Initialisation
+
+**Fabrication Note v1.0, AsTeRICS Foundation**
+
+![FLipMouseLogo](./img/flipmouseLogo.png)
+
+# Scope
+
+FLipMouse and FLipPad use from version 3 onward an __Arduino Nano RP2040 Connect__ platform.
+
+The big advantage over the TeensyLC from version 2, this controller has much more RAM & ROM and already contains the ESP32, which is used for the Bluetooth connectivity.
+
+To fully use the update procedures from the WebGUI, the Arduino needs to be programmed initially:
+
+* __esp32_addon_bootloader:__ Bootloader Code to update the ESP32 BLE Mouse/Keyboard firmware without esptool.py
+* __esp32_mouse_keyboard:__ Program the BLE HID over GATT firmware
+* __FLipMouse/FLipPad firmware:__ Program the RP2040 with the current FLipMouse / FLipPad Firmware 
+
+# Preparation
+
+## Material
+
+| Nr.  | Description                        | Source                                                       | Image                                                        |
+| ---- | ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| 1    | Arduino Nano RP2040 Connect        | https://store.arduino.cc/products/arduino-nano-rp2040-connect | ![A new Arduino Nano RP2040 connect](./img/rp2040_unmarked.png) |
+
+__Note: Material will be referenced in square brackets: []__
+
+## Tools / Requirements
+
+| Nr.  | Description                       | Source                                                       |
+| ---- | --------------------------------- | ------------------------------------------------------------ |
+| 1    | Terminal + Python3                | Install python according to your OS                          |
+| 2    | esptool                           | Install via pip: `pip install esptool` (if it cannot be executed from a terminal, run this command as root) |
+| 2    | Permanent marker (red/blue/green) | DYI store, paper store (possibly any store)                  |
+
+__Note: Tools will be referenced in curly brackets: {}__
+
+<div style="page-break-after: always; break-after: page;"></div>
+# Procedure
+
+1. Attach the Arduino Nano RP2040 Connect _[1]_ to the computer
+2. Open a terminal
+3. Call the script: `rp2040_prepare.py -t <FM/FP> -p <serial port>`
+
+_-t_ Select the firmware to be flashed, either FP for FLipPad, FM for FLipMouse of FB for FABI (FP & FB are not finished yet)
+
+_-p_ Select a serial port which should be flashed (normally COMxx on Windows, /dev/ttyxxx on Linux)
+
+# Testing
+
+Not available, if procedure is followed, the software is flashed correctly:
+
+* __Blue blinking__ LED for a flashed Bluetooth firmware
+
+## Documentation
+
+For each produced batch, fill out one document __template_arduino_init_production.ots__ and save it as: `arduino_init_<date>.ods`(e.g.: arduino_init_20221118.ods)
+
+
+## Updating the firmware builds to be flashed
+
+
+
+1. Replace `bootloader.bin`,`esp32_addon_bootloader.bin`, `ota_initial_data.bin` and `partition-table.bin`with a current build from: _esp32_addon_bootloader/build/esp32_addon_bootloader.bin_
+2. Replace `mousekeyboard.bin` with a current build from: _esp32_mouse_keyboard/build/esp32_mouse_keyboard.bin_
+3. Replace `FM.uf2`, `FP.uf2`, `FB.uf2` with current builds from the FLipWare/FabiWare repositories (build with Arduino and select _Sketch->Export compiled binary_)
+4. Replace `serialflasher1.uf2` with a new build from the serialflasher1.ino sketch from this directory (build with Arduino and select _Sketch->Export compiled binary_)
+5. Replace `serialflasher2.uf2` with a new build from the serialflasher2.ino sketch from this directory (build with Arduino and select _Sketch->Export compiled binary_)
+7. __Write down the current GIT tags (releases) or commit numbers for the builds to _VERSIONS.md_ __
+
+
+
+## Insights
+
+
+
+This tool performs following steps:
+
+1. Flashing the serialflasher1.uf2 firmware calling `uf2conv.py`tool
+2. Flashing the esp32_addon_bootloader firmware with `esptool.py`
+3. Flashing the serialflasher2.uf2 firmware calling `uf2conv.py` tool
+4. Flash the esp32_mouse_keyboard_firmware (included in rp2040_prepare.py)
+5. Reset the Arduino to UF2 download mode by opening the given serial port with 1200Baud and closing it
+6. Flashing the FM/FB/FP.uf2 firmware calling `uf2conv.py`tool
+7. Verifying that everything worked by sending "AT BC $ID" to the serial port, which returns the version of the BLE module. This is printed on the command line.
+8. Start over (wait until serial port is removed and a new one is detected)
+
+
+

Documentation/Fabrication/rp2040_preparation/VERSIONS.md

@@ -0,0 +1,21 @@
+# Versions for intermediate serial/usb passthrough sketches
+
+serialflasher1.uf2		no version code, first commit
+serialflasher2.uf2		no version code, first commit
+
+# Versions for esp32_addon_bootloader binary files
+
+__Note:__ You need to update all of these files!
+
+esp32_addon_bootloader.bin	5bd3413 (RP2040 branch)
+ota_data_initial.bin		5bd3413 (RP2040 branch)
+bootloader.bin			5bd3413 (RP2040 branch)
+partition-table.bin		5bd3413 (RP2040 branch)
+
+# Versions for the esp32_mouse_keyboard binary file
+
+esp32_mouse_keyboard.bin	fa59627 (RP2040 branch)
+
+# Versions for FLipWare
+
+FM.uf						712338a (RP2040 branch)