.gitignore

@@ -2,3 +2,4 @@
 **.rhl
 archive/
 **cam/
+**node_modules/
\ No newline at end of file

LOG.md

-## DEX
+## DEX LOG
+
+## 2019 11
+
+https://github.com/ChrisEberl/Python_DIC
+
+### Vision Controller Hello-World
+
+We're currently working to build a computer vision based displacement sensing method for the DEX. Since our machine (or, many machines manufactured by novices / in the public domain) are liable to flex (indeed, nothing is infinitely stiff!), the thought is to measure local displacements of the sample, at the sample, rather than measuring open-loop through the machine's structure.
+
+To spin this up, I've written a small / barebones subpixel template tracker in the browser, in cuttlefish. This is conveniently lightweight - the whole cycle (image collection -> analysis) can happen at ~ 10Hz, which is not splendid, but not diabolical either.
+
+![vd](video/2019-11-17_micrometers-cv.mp4)
+
+Here we can see a desktop test - I am reading the X- position from my tracking system on to a chart, and moving the tracker on a linear stage. This system resolves ~ 15um, which is not bad for a proof of concept.
+
+## 2019 10
 
 Re-did the machine last week, now much simpler:
 
 ![dex](images/2019-09-27_DEX-CAD.png)
 
-... 
+## Comparison to Instron 4411 (2019 10)
+
+To see how we do against a real instron, I tested identical samples on the DEX as well as on an Instron '4411' with a 5kN load cell. In the plot below (I'm using cuttlefish to plot the .csv that I saved from Bluehill, the Instron software), the leftmost plot is taken on the 4411, and the lazier slope belongs to the DEX.
+
+While the samples fail around the same load, the difference in elongation is ~ 1.5mm wide: this is almost surely the machine's own deflection, stretch in the belts, etc.
+
+![dex-compare](images/2019-10-17_data-compare.png)
+
+This obviously warrants correction. One way to do this is to build a stiffer machine, however, we will be chasing up the cost and complexity if we do this. Rather, we should throw some more control at it. To start, we can circle back to our attempts at [subpixel tracking](https://gitlab.cba.mit.edu/calischs/subpixel_tracking), or attach a small linear stage directly to our fixturing elements. For this, I am imagining something like the [AMS5311](https://ams.com/as5311), which should do some 12 bits inside of a 2mm throw (for 0.4um resolution). Either can be added to existing systems, given network controllers / modular browser code. Since I want to integrate it elsewhere, it's likely that the camera option comes first.
+
+**update** the new machine uses a ballscrew transmission, not a belt (as used here) which should elminate most of the creep tested here against the 4411. forward progress has been made with a vision based controller, to improve further, but has not been characterized yet.
 
 #### Some Force Maths (and a .xlsx file)
 

README.md

 # The Displacement Exercise (DEX)
 
-DEX is a small materials testing machine that should be capable of running tensile and compressive tests at up to 600N of force.
+The DEX is an open source piece of materials testing equipment. The machine can be manufactured by anyone with access to a laser cutter with at least a 24x12" bed, or a milling machine of similar or larger size, and nearly any FDM 3D Printer. A bill of materials of purchased parts required to complete the machine is below, totaling some ~ $500 USD.
 
-| | |
-| --- | --- |
-| ![dex](images/2019-10-17_dex-01.jpg) | ![dex](images/2019-10-17_dex-03.jpg) |
+The machine uses a NEMA 23 stepper motor and a small ball screw to exert force on samples, and any off the shelf load-cell to measure stress. At the lab, we use [squidworks](https://gitlab.cba.mit.edu/squidworks/squidworks) controllers to operate the machine, but a standalone controller written for Arduino and with a JS frontend is [here](controller). 
+
+![dex](images/2020-02-11_dex-render.png)
+
+![dex-alive](images/2020-07-12_dex-on-desk-01.jpg)
+
+![control](images/2020-07-11_dex-tools.png)
 
 ## Operating Principle
 
@@ -12,21 +16,22 @@ A [stress - strain plot](https://en.wikipedia.org/wiki/Stress%E2%80%93strain_cur
 
 ![ss curve](images/stress-strain.jpg)
 
-To generate these curves, the DEX slowly pulls samples (normally some 'dogbone' shape [below](#testing-notes)) apart, while measuring the amount that it stretches (~ the strain), and the amount of force it exerts as it is stretched (~ the stress). These types of machine are common in industry, commonly referred to by their leading brand name 'Instron', or as 'Universal Testing Machines'.
+To generate these curves, the DEX slowly pulls samples (normally some 'dogbone' shape [below](#testing-notes)) apart, while measuring the amount that it stretches (~ the strain), and the amount of force it exerts as it is stretched (~ the stress). These types of machine are common in industry, often referred to by their leading brand name 'Instron', or as 'Universal Testing Machines' (UTM).
 
-## Hardware
+## Comparison to the Instron 4411
 
-The DEX is an open-source piece of materials testing equipment. The machine can be manufactured by anyone with access to a laser cutter with at least a 24x12" bed, and nearly any FDM 3D Printer. A bill of materials of purchased parts required to complete the machine is below, totaling some ~ $500 USD.  
+I compared results from the most recent DEX build to the Instron 4411 we have in the lab. Some errors still exist: it could be the case that the load cell needs better calibration: my largest calibration weights are near 2kg, but these loads approach 8kgf. I'm not sure how much nonlinearity exists in COTS (and cheap) loadcells like this, but I have *heard* they are *fairly* linear, so certainly we can do better than heresay. There is certainly some flex in the machine itself, but much less than earlier versions. To improve this, the DEX can be fabricated in Phenolic or some other composite, rather than Acrylic as used here. Finally, fixturing could be greatly improved, I believe some creep exists in the jaws as well. I have ordered some parts to test better (off the shelf) steel clamps. 
 
-The machine is made largely from [laser cut](https://hackaday.com/2015/09/03/how-to-build-anything-using-delrin-and-a-laser-cutter/) [delrin](https://hackaday.com/2015/09/22/drawbacks-of-lased-delrin-and-how-to-slip-around-them/) and 3D printed (commodity FDM) parts.
+![dt1](data/2020-07-12_compare-dex-4411/2020-07-12_compare-dex-4411-01.png)
+![dt2](data/2020-07-12_compare-dex-4411/2020-07-12_compare-dex-4411-02.png)
 
-More detailed documentation will follow.
+## Hardware
 
 ### CAD
 
-CAD for the machine is available in this Repo, [under `cad/fusion`](https://gitlab.cba.mit.edu/jakeread/displacementexercise/tree/master/cad/fusion) - the `.f3z` file is a Fusion 360 parametric model of the machine. To source parts, consult the BOM below.
+CAD for the machine is available in this Repo, [under `cad/`](cad/) - the `.f3z` file is a Fusion 360 parametric model of the machine, and the `.3dm` model is a complete Rhino3D Model, with purchase parts included. To source parts, consult the BOM below.
 
-![dex](images/2019-09-27_DEX-CAD.png)
+![dex](images/2020-02-11_dex-parts.png)
 
 ### BOM
 
@@ -34,85 +39,64 @@ Part numbers are from [McMaster Carr](http://mcmaster.com) unless otherwise link
 
 | Part | Spec | Count | Notes | PN / Link | Cost / Per |
 | --- | --- | ---: | --- | ---: | ---: |
-| Delrin (Acetal) Cast Sheet | 24x12", 0.25" Thick | 2 | Fits on 24x18" w/ no mistakes | 8573K35 | $50.49 / 1 |
+| Acrylic Sheet | 24x12", 0.25" Thick | 2 | - | 8505K755 | $19.93 / 1 |
 | PLA 'Tough' |  | ~ 300g | Many 3DP Mechanical Bits | [Matter Hackers M6E9T65K](https://www.matterhackers.com/store/l/light-blue-pro-series-tough-pla-filament-175mm-1kg/sk/M6E9T65K) | $52.00 / 1kg |
-| 625ZZ Bearings | 5x16x5  | 24 | - | [VXB 625ZZ](https://www.vxb.com/20-625ZZ-Shielded-5mm-Bore-Diameter-Miniature-p/625zz20.htm) | $24.95 / 20 |
-| Bearing Shims | 5x10x0.5 | 37 | - | 98055A098 | $8.62 / 50 |
-| Carriage Shoulders | M4x5x6 | 12 | - | 92981A146 | $2.16 / 1 |
-| Reduction Shoulder | M4x5x10 | 1 | - | 92981A030 | $2.32 / 1 |
-| Idler Shoulders | M4x5x20 | 5 | - | 92981A042 | $2.33 / 1 |
-| NEMA 23 Stepper Motor | > 56mm Can Length | 1 | Spec Shaft with Pinion | [Stepper Online](https://www.omc-stepperonline.com/nema-23-stepper-motor/nema-23-bipolare-1-8deg-1-26nm-178-4oz-in-2-8a-2-5v-57x57x56mm-4-fili.html) | $14.83 / 1 |
+| 625ZZ Bearings | 5x16x5  | 13 | - | [VXB 625ZZ](https://www.vxb.com/20-625ZZ-Shielded-5mm-Bore-Diameter-Miniature-p/625zz20.htm) | $24.95 / 20 |
+| Bearing Shims | 5x10x0.5 | 26 | - | 98055A098 | $8.62 / 50 |
+| Carriage Shoulders | M4x5x6 | 13 | - | 92981A146 | $2.16 / 1 |
+| NEMA 23 Stepper Motor | 56mm Can Length | 1 | Spec Shaft with Pinion | [Stepper Online](https://www.omc-stepperonline.com/nema-23-stepper-motor/nema-23-bipolare-1-8deg-1-26nm-178-4oz-in-2-8a-2-5v-57x57x56mm-4-fili.html) | $14.83 / 1 |
 | GT2 Pinion | 20T | 1 | Spec Shaft with NEMA 23 | [Amazon](https://www.amazon.com/Saiper-GT2-Teeth-6-35mm-Synchronous/dp/B07MGMBX3N/) (or) [RobotDigg](https://www.robotdigg.com/product/226/20-Tooth-2GT-Pulley-10pcs-per-lot) | $9.96 / 5 |
-| GT2 Closed Loop Belt | 280T, 6mm Wide | 1 | - | [Amazon](https://www.amazon.com/280-2GT-6-Timing-Belt-Closed-Loop/dp/B014SLWP68/) (or) [RobotDigg](https://www.robotdigg.com/product/283/260mm-264mm-268mm-280mm-284mm-288mm-or-294mm-gt2-endless-belt) | $15.88 / 10 |
-| GT3 Open Loop Belt | ~ 1m, 9mm Wide | 1 | - | [Amazon](https://www.amazon.com/Ochoos-Timing-Rubber-Backlash-5Meters/dp/B07MWD9D7V/) (or) [RobotDigg](https://www.robotdigg.com/product/597/3GT-9mm-or-6mm-wide-open-ended-belt) | $15.00 / 1 |
-| 6806 Bearing | 30x42x7mm | 2 | x | 6806-2RS [VXB](https://www.vxb.com/6806-2RS-Bearing-30x42x7-Sealed-p/6806rs.htm) | $12.95 / 1 |
-| M3 Inserts | Tapered, 3.8mm Tall | ~ 300 | - | 94180A331 | $12.92 / 100 |
+| GT2 Closed Loop Belt | 200T (400mm long), 6mm Wide | 1 | - | [Amazon](https://www.amazon.com/400-2GT-6-Timing-Belt-Closed-Loop/dp/B014U7OSVA/) (or) [RobotDigg](https://www.robotdigg.com/product/286) | $15.88 / 10 |
+| 1204 x 400mm SFU Ball Screw Kit | | 1 | | [Amazon](https://www.amazon.com/SFU1204-Ballscrew-RM1204-Housing-Machine/dp/B076PCVC8F/)
+| M3 Inserts | Tapered, 3.8mm Tall | 200 | - | 94180A331 | $12.92 / 100 |
 | M4 Inserts | Tapered, 4.7mm Tall | 16 | - | 94180A351 | $14.96 / 100 |
-| M5 Inserts | Tapered, 6.7mm Tall | 4 | - | 94180A361 | $12.00 / 50 |
-| M3 Washers | 18-8 Standard Flat | 300 | - | 93475A210 | $1.62 / 100 |
 | SHCS | M3x16 | 100 | Pinning T- to the wall, and pulley endmatter | 91292A115 | $5.87 / 100 |
-| SHCS | M3x20 | 100 | Pinning T- to one another (?) | 91292A123 | $6.78 / 100 |
-| SHCS | M3x25 | 100 | Pinning T- and X-es together | 91292A020 | $7.23 / 100 |
-| SHCS | M3x45 | 8 | Pinning the 'squat' together | 91292A025 | $12.21 / 50 |
-| FHCS | M3x10 | 30 | Pinning blisters to faces | 92125A130 | $5.81 / 100 |
-| FHCS | M3x25 | (?) | - | 92125A138 | $11.50 / 100 |
-| Steel Dowel Pins | 5x8mm | 10 | - | 91585A506 | $8.40 / 25 |
-| Feet | M4 Stud, 15x15mm | - | - | 93115K881 | $1.78 / 1 |
-| **Approximate Mechanical Total** | | | | | **$446.80** |
+| M3 Washers | 18-8 Standard Flat | 300 | - | 93475A210 | $1.62 / 100 |
+| SHCS | M4x16 | 6 | Mounting Ball Nut | 91292A118 | $8.13 / 100 |
+| SHCS | M5x20 | 4 | Motor Mounting | 91292A121 | $9.03 / 100 |
+| Locknut | M5 | 4 | Motor Mounting | 93625A200 | $6.46 / 100 |
+| SHCS | M8x30 | 2 | Loadcell Fixturing | 91292A149 | $10.13 / 25 |
+| Feet | M4 Stud, 15x15mm | 3 | - | 93115K881 | $1.78 / 1 |
+| Shaft Collar | 8mm Diameter, Flanged | - | - | 9723T12 | $60.14 |
 | Loadcell(s) | 10, 30, or 50kg | 1 | Choose Range for Sensitivity | [Amazon 50kg](https://www.amazon.com/Pressure-Force-S-type-Sensor-Cable/dp/B01F6IOW3G/) [Amazon 30kg](https://www.amazon.com/Pressure-Force-S-type-Sensor-Cable/dp/B01F6IOWDG/) [Amazon 10kg](https://www.amazon.com/Pressure-Force-S-type-Sensor-Cable/dp/B01F6IOW4K/) | $39.00 / 1|
 | Loadcell Amplifier | HX711 | 1 | - | [Sparkfun 13879](https://www.sparkfun.com/products/13879) | $9.95 / 1 |
 | Power Supply | 350W 24V LRS-350-24 | 1 | - | [Amazon](https://www.amazon.com/MEAN-WELL-LRS-350-24-350-4W-Switchable/dp/B013ETVO12/) | $32.25 / 1 |
-| **Rough Control Total: Incomplete** | | | | | **81.20** |
-| **All Up** | | | | | **$528.00** |
 
-## Control and Interface
+### Choice of Sheet Material
 
-DEX runs a [squidworks](https://gitlab.cba.mit.edu/squidworks/squidworks) controller. The `dex` branches of [cuttlefish](https://gitlab.cba.mit.edu/squidworks/cuttlefish) and [ponyo](https://gitlab.cba.mit.edu/squidworks/ponyo) contain code that is known to work with the machine. Again, more documentation for these controllers is coming, for now - consult the repositories.
+Here, I list Acrylic Sheet as the main chassis material. With acrylic, the machine can be manufactured easily on a laser cutter. However, it should also be possible to build the DEX with different sheet material. Lately, I have been using Phenolic as a chassis material: it can be milled on a ShopBot or similar router, and performs much better than Acrylic, with around 11GPA flexural strength (vs. Acrylic's ~ 3GPA). Acrylic is best bonded with Acrylic Cement, a solvent that welds the plastic to itself. Phenolic is best bonded with a two-part epoxy: I use a 20 minute working life epoxy, and nearly any type will do.
 
-![c1](images/2019-10-17_dex-controller.png)
-![c2](images/2019-10-17_dex-controller-zoom.png)
+## Control and Interface: Standalone 
 
-## Comparison to Instron 4411
+I recently built a [standalone controller](controller) for this thing, it's written in Arduino and vanilla JS for Node (to serve the app and connect to the machine) and the Browser. 
 
-To see how we do against a real instron, I tested identical samples on the DEX as well as on an Instron '4411' with a 5kN load cell. In the plot below (I'm using cuttlefish to plot the .csv that I saved from Bluehill, the Instron software), the leftmost plot is taken on the 4411, and the lazier slope belongs to the DEX.
+![dex-alive](images/2020-07-12_dex-on-desk-02.jpg)
 
-While the samples fail around the same load, the difference in elongation is ~ 1.5mm wide: this is almost surely the machine's own deflection, stretch in the belts, etc.
+## Control and Interface: Squidworks
 
-![dex-compare](images/2019-10-17_data-compare.png)
+DEX is designed to run a [squidworks](https://gitlab.cba.mit.edu/squidworks/squidworks) controller. The `dex` branches of [cuttlefish](https://gitlab.cba.mit.edu/squidworks/cuttlefish) and [ponyo](https://gitlab.cba.mit.edu/squidworks/ponyo) contain code that is known to work with the machine. For more info on the controllers, please consult those repositories. In all, controlling the machine can be achieved in any number of ways, on needs only to control one stepper motor and read one load cell.
 
-This obviously warrants correction. One way to do this is to build a stiffer machine, however, we will be chasing up the cost and complexity if we do this. Rather, we should throw some more control at it. To start, we can circle back to our attempts at [subpixel tracking](https://gitlab.cba.mit.edu/calischs/subpixel_tracking), or attach a small linear stage directly to our fixturing elements. For this, I am imagining something like the [AMS5311](https://ams.com/as5311), which should do some 12 bits inside of a 2mm throw (for 0.4um resolution). Either can be added to existing systems, given network controllers / modular browser code. Since I want to integrate it elsewhere, it's likely that the camera option comes first.
+![c1](images/2019-10-17_dex-controller.png)
+![c2](images/2019-10-17_dex-controller-zoom.png)
 
-## Testing Notes
+#### Vision for Displacement Sensing
 
-The D683 ASTM Dogbones:
+We're currently working to build a computer vision based displacement sensing method for the DEX. Since our machine (or, many machines manufactured by novices / in the public domain) are liable to flex (indeed, nothing is infinitely stiff!), the thought is to measure local displacements of the sample, at the sample, rather than measuring open-loop through the machine's structure. I started this with a small sample code, noted in [the log](LOG.md), and have gone through integrating this into the machine's controller.
 
-![dogbones](images/astm_d-638_bonesizes.jpg)
+![dex-vision](images/2019-11_dex-cam.jpg)
 
-# Roadmap
+The controller involves a calibration stage, where I operate the machine in open-loop, stepping in increments with no load exerted on the machine. I track the marker's displacements, building a map between the known ballscrew displacements and the tracked pixel positions.
 
-*2019-10-17*
+![dex-calib](images/2019-11_dex-vision-calibration.png)
 
-One complete DEX exists in the MIT CBA shop, and has been validated against an Instron 4411. Current efforts are twofold:
+Once I have this calibration, I save the function fit, and use it to read positions back while the machine is loaded.
 
-(1) Working with the [materiom](https://materiom.org/) project (whose mission: to provide open data on how to develop bio-inspired materials for a circular economy), and the [fablab at cic](https://cic.com/fab), we are replicating the current design outside of the CBA shop, and building documentation while we do.
+![dex-use](images/2019-11_dex-vision-controller.png)
 
-(2) To improve the machine's test accuracy, we are integrating CV processing into the control architecture, to use [subpixel tracking](https://gitlab.cba.mit.edu/calischs/subpixel_tracking). Further controller improvements from the squidworks project will also bring rate control on-board.
+This nearly works, but needs some improvement. To go about doing this at a higher fidelity, I am working on integrating Python scripts into squidworks controllers, which will let me tie OpenCV codes into dataflow controllers. Another escalation will involve using DIC (digital image correlation) codes to observe the entire structure's deflections during testing, which should render even higher quality testing results.
 
-## Notes
-```
-- Where to build logs go? This repo -> gitlab, mtm.cba, etc.
-- Future integration of Temperature and Humidity Sensors
-- Higher quality integration of load-cell amplifier
-- Developing control for Cyclic Loading, Fatigue, etc.
-- Developing direct upload / websocket-to-database tools
-- Dec. 5: controllers -> CIC and London
-- Cuttlefish: manipulation, understanding, computing on test datasets in the browser.
-```
+## Testing Notes
+
+The D683 ASTM Dogbones:
 
-## TODO
-```
-- encapsulate branches for ponyo, cuttlefish.
-- bs ?
-- put rpi setup back on desk with dex, branch, close
-- revisit with cameras, rate control
-```
+![dogbones](images/astm_d-638_bonesizes.jpg)

controller/README.md

+# DEX Controller
+
+I've decided to roll a standalone controller for DEX. I've made a little ad-hoc breadboard circuit to connect one stepper driver, one load cell amp, to an Adafruit Feather M4 - an arduino variant. 
+
+The controller is fairly simple. The embedded code (which can be built with Arduino) reads command codes from the usb-serial port. These commands tell the machine to:
+- move a number of steps 
+- tare the loadcell 
+- read the loadcell 
+
+Instructions to the machine are done in low-level appropriate data types: steps are steps, not mm. Readings are returned as raw ADC readings. Conversions between machine-units and real-world units are done in JavaScript.
+
+One javascript launches a webserver: that's `js/dexs.js` - you should be able to run it (after installing node) by navigating to the `js` directory here and doing `node dexs.js`. It will announce an IP address and port, point your browser at that. Important! Launch the tool when the DEX machine is already plugged into USB.
+
+The client javascript can jog the machine, tare the loadcell, and perform tests. Tests are saved as .csv files.
+
+Hopefully enough of the code is self-explanatory, more documentation can come if it's requested. 
+
+![controller](/images/2020-07-11_dex-tools.png)
+![controller](/images/2020-07-12_dex-on-desk-02.jpg)
+
+## Install
+
+``Install Node.JS``  
+``npm install express``  
+``npm install ws``  
+``npm install serialport``  
+``npm install esm``  
\ No newline at end of file

controller/embedded/.gitignore

+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch

controller/embedded/.travis.yml

+# Continuous Integration (CI) is the practice, in software
+# engineering, of merging all developer working copies with a shared mainline
+# several times a day < https://docs.platformio.org/page/ci/index.html >
+#
+# Documentation:
+#
+# * Travis CI Embedded Builds with PlatformIO
+#   < https://docs.travis-ci.com/user/integration/platformio/ >
+#
+# * PlatformIO integration with Travis CI
+#   < https://docs.platformio.org/page/ci/travis.html >
+#
+# * User Guide for `platformio ci` command
+#   < https://docs.platformio.org/page/userguide/cmd_ci.html >
+#
+#
+# Please choose one of the following templates (proposed below) and uncomment
+# it (remove "# " before each line) or use own configuration according to the
+# Travis CI documentation (see above).
+#
+
+
+#
+# Template #1: General project. Test it using existing `platformio.ini`.
+#
+
+# language: python
+# python:
+#     - "2.7"
+#
+# sudo: false
+# cache:
+#     directories:
+#         - "~/.platformio"
+#
+# install:
+#     - pip install -U platformio
+#     - platformio update
+#
+# script:
+#     - platformio run
+
+
+#
+# Template #2: The project is intended to be used as a library with examples.
+#
+
+# language: python
+# python:
+#     - "2.7"
+#
+# sudo: false
+# cache:
+#     directories:
+#         - "~/.platformio"
+#
+# env:
+#     - PLATFORMIO_CI_SRC=path/to/test/file.c
+#     - PLATFORMIO_CI_SRC=examples/file.ino
+#     - PLATFORMIO_CI_SRC=path/to/test/directory
+#
+# install:
+#     - pip install -U platformio
+#     - platformio update
+#
+# script:
+#     - platformio ci --lib="." --board=ID_1 --board=ID_2 --board=ID_N

controller/embedded/.vscode/extensions.json

+{
+    // See http://go.microsoft.com/fwlink/?LinkId=827846
+    // for the documentation about the extensions.json format
+    "recommendations": [
+        "platformio.platformio-ide"
+    ]
+}

controller/embedded/include/README

+
+This directory is intended for project header files.
+
+A header file is a file containing C declarations and macro definitions
+to be shared between several project source files. You request the use of a
+header file in your project source file (C, C++, etc) located in `src` folder
+by including it, with the C preprocessing directive `#include'.
+
+```src/main.c
+
+#include "header.h"
+
+int main (void)
+{
+ ...
+}
+```
+
+Including a header file produces the same results as copying the header file
+into each source file that needs it. Such copying would be time-consuming
+and error-prone. With a header file, the related declarations appear
+in only one place. If they need to be changed, they can be changed in one
+place, and programs that include the header file will automatically use the
+new version when next recompiled. The header file eliminates the labor of
+finding and changing all the copies as well as the risk that a failure to
+find one copy will result in inconsistencies within a program.
+
+In C, the usual convention is to give header files names that end with `.h'.
+It is most portable to use only letters, digits, dashes, and underscores in
+header file names, and at most one dot.
+
+Read more about using header files in official GCC documentation:
+
+* Include Syntax
+* Include Operation
+* Once-Only Headers
+* Computed Includes
+
+https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html

controller/embedded/lib/README

+
+This directory is intended for project specific (private) libraries.
+PlatformIO will compile them to static libraries and link into executable file.
+
+The source code of each library should be placed in a an own separate directory
+("lib/your_library_name/[here are source files]").
+
+For example, see a structure of the following two libraries `Foo` and `Bar`:
+
+|--lib
+|  |
+|  |--Bar
+|  |  |--docs
+|  |  |--examples
+|  |  |--src
+|  |     |- Bar.c
+|  |     |- Bar.h
+|  |  |- library.json (optional, custom build options, etc) https://docs.platformio.org/page/librarymanager/config.html
+|  |
+|  |--Foo
+|  |  |- Foo.c
+|  |  |- Foo.h
+|  |
+|  |- README --> THIS FILE
+|
+|- platformio.ini
+|--src
+   |- main.c
+
+and a contents of `src/main.c`:
+```
+#include <Foo.h>
+#include <Bar.h>
+
+int main (void)
+{
+  ...
+}
+
+```
+
+PlatformIO Library Dependency Finder will find automatically dependent
+libraries scanning project source files.
+
+More information about PlatformIO Library Dependency Finder
+- https://docs.platformio.org/page/librarymanager/ldf.html

controller/embedded/platformio.ini

+; PlatformIO Project Configuration File
+;
+;   Build options: build flags, source filter
+;   Upload options: custom upload port, speed and extra flags
+;   Library options: dependencies, extra library storages
+;   Advanced options: extra scripting
+;
+; Please visit documentation for the other options and examples
+; https://docs.platformio.org/page/projectconf.html
+
+[env:adafruit_feather_m4]
+platform = atmelsam
+board = adafruit_feather_m4
+framework = arduino

controller/embedded/src/comm/cobs.cpp

+/*
+utils/cobs.cpp
+
+Jake Read at the Center for Bits and Atoms
+(c) Massachusetts Institute of Technology 2019
+
+This work may be reproduced, modified, distributed, performed, and
+displayed for any purpose, but must acknowledge the squidworks and ponyo projects.
+Copyright is retained and must be preserved. The work is provided as is;
+no warranty is provided, and users accept all liability.
+*/
+
+#include "cobs.h"
+// str8 crib from
+// https://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing
+
+#define StartBlock()	(code_ptr = dst++, code = 1)
+#define FinishBlock()	(*code_ptr = code)
+
+size_t cobsEncode(uint8_t *ptr, size_t length, uint8_t *dst){
+  const uint8_t *start = dst, *end = ptr + length;
+  uint8_t code, *code_ptr; /* Where to insert the leading count */
+
+  StartBlock();
+  while (ptr < end) {
+  	if (code != 0xFF) {
+  		uint8_t c = *ptr++;
+  		if (c != 0) {
+  			*dst++ = c;
+  			code++;
+  			continue;
+  		}
+  	}
+  	FinishBlock();
+  	StartBlock();
+  }
+  FinishBlock();
+  // write the actual zero,
+  *dst++ = 0;
+  return dst - start;
+}
+
+size_t cobsDecode(uint8_t *ptr, size_t length, uint8_t *dst)
+{
+	const uint8_t *start = dst, *end = ptr + length;
+	uint8_t code = 0xFF, copy = 0;
+
+	for (; ptr < end; copy--) {
+		if (copy != 0) {
+			*dst++ = *ptr++;
+		} else {
+			if (code != 0xFF)
+				*dst++ = 0;
+			copy = code = *ptr++;
+			if (code == 0)
+				break; /* Source length too long */
+		}
+	}
+	return dst - start;
+}

controller/embedded/src/comm/cobs.h

+/*
+utils/cobs.h
+
+consistent overhead byte stuffing implementation
+
+Jake Read at the Center for Bits and Atoms
+(c) Massachusetts Institute of Technology 2019
+
+This work may be reproduced, modified, distributed, performed, and
+displayed for any purpose, but must acknowledge the squidworks and ponyo projects.
+Copyright is retained and must be preserved. The work is provided as is;
+no warranty is provided, and users accept all liability.
+*/
+
+#ifndef UTIL_COBS_H_
+#define UTIL_COBS_H_
+
+#include <arduino.h>
+
+size_t cobsEncode(uint8_t *src, size_t len, uint8_t *dest);
+
+size_t cobsDecode(uint8_t *src, size_t len, uint8_t *dest);
+
+#endif

controller/embedded/src/comm/cobsserial.cpp

+/*
+cobsserial.cpp 
+
+COBS delineated serial packets 
+
+Jake Read at the Center for Bits and Atoms
+(c) Massachusetts Institute of Technology 2019
+
+This work may be reproduced, modified, distributed, performed, and
+displayed for any purpose, but must acknowledge the squidworks and ponyo projects.
+Copyright is retained and must be preserved. The work is provided as is;
+no warranty is provided, and users accept all liability.
+*/
+
+#include "cobsserial.h"
+
+COBSSerial::COBSSerial(){
+}
+
+void COBSSerial::init(void){
+  // start the port... 
+  Serial.begin(9600);
+}
+
+void COBSSerial::loop(void){
+  while(Serial.available()){
+    if(_pl > 0) break;
+    _encodedPacket[_bwp] = Serial.read();
+    if(_encodedPacket[_bwp] == 0){
+      // indicate we recv'd zero
+      // CLKLIGHT_TOGGLE;
+      // decode from rx-ing frame to interface frame,
+      size_t dcl = cobsDecode(_encodedPacket, _bwp, _packet);
+      _pl = dcl; // this frame now available, has this length,
+      // reset byte write pointer
+      _bwp = 0;
+    } else {
+      _bwp ++;
+    }
+  }
+}
+
+boolean COBSSerial::hasPacket(void){
+  if(_pl > 0){
+    return true;
+  } else {
+    return false;
+  }
+}
+
+void COBSSerial::getPacket(uint8_t **pck, uint16_t *pl){
+  *pck = _packet;
+  *pl = _pl;
+}
+
+void COBSSerial::clearPacket(void){
+  // frame consumed, clear to write-in,
+  _pl = 0;
+}
+
+void COBSSerial::sendPacket(uint8_t *pck, uint16_t pl){
+  size_t encLen = cobsEncode(pck, pl, _encodedOut);
+  Serial.write(_encodedOut, encLen);
+}