doc: brief project documentation

CHANGELOG.md

@@ -0,0 +1,6 @@
+v0
+==
+
+first prototype containing testers for USB A, micro-B, and C.
+not tested yet.
+only shows the features, and does not interpret them.

README.md

@@ -1,7 +1,49 @@
-these are the hardware design files for **insert project name here**.
-
-purpose
-=======
+The USB micro-B and C cable tester identifies functionalities supported by USB cables.
+It helps figuring out if a USB cable is for charging or to transfer data.
+It supports type A to micro-B, A to C, and C to C USB cables.
 
 usage
 =====
+
+- ensure the tester has a non-empty battery in the CR2032/2025, or is externally powered through the USB power port
+- plug one end of the cable in one of the host ports
+- plug the other end of the cable in one of the devices ports
+- the tester will identify the cable's capabilities
+
+design choice
+=============
+
+features
+--------
+
+do:
+
+- USB micro-B: still wide-spread and popular for charging devices
+- USB type-A: still the de-facto host plug
+- USB type-C: becoming the standard for battery operated devices
+- C to C: often used for high power charging of phones and laptops
+- battery operated: it's a very simple device, and this avoids needing to require external power
+- power port: in case you have no battery or it runs out
+- USB 3.0: because it is hard to identify if C-C cable support Super-Speed
+
+don't:
+
+- small: no need to build it as compact as possible
+- A or micro-B 3.0: the connectors that support it are obvious, and it's rare they are used for anything else than Super-Speed transfer (plus they are less common or problematic)
+- Power Delivery capabilities: this requires complex host software communicating with the eMarker chip in the cable
+- OTG: even if detecting this functionality is easy, micro-B OTG adapters are not popular anymore
+
+future:
+
+- interpret the supported functionalities to show the cable purpose
+- show a simple cable type result, and not just the individual capabilities
+
+alternatives
+------------
+
+- [USB micro-B cable tester](https://www.cuvoodoo.info/cuvoodoo-gadget-micro-usb-cable-tester-v2/): only does micro-B cables
+- [USB A-C cable tester](https://www.cuvoodoo.info/cuvoodoo-gadget-usb-a-to-usb-c-cable-tester-v1/): only does USB type A to type C cables
+- [USB C-C cable tester](https://www.cuvoodoo.info/cuvoodoo-gadget-usb-c-cable-tester-v2/): only does USB type C to type C cables
+- [DT3 Data Cable Detection Board](https://www.aliexpress.com/item/1005006302832038.html): does not check shield, battery charging, USB 3.0
+- [USB Cable Checker 2](https://www.tindie.com/products/bittradeone/usb-cable-checker-2-assembled/): too complex and expensive
+- [USB Cable Tester](https://github.com/alvarop/usb_c_cable_tester): only for USB-C and you have to understand and interpret the signals