diff --git a/README.md b/README.md
index 2cda4de..81b196b 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,101 @@
-these are the hardware design files for **insert project name here**.
+the CuVoodoo USB hub is a 7-port USB 2.0 hub meant for device testing.
 
 purpose
 =======
 
+most USB hub are super cheap and crappy, leading the poor connection connection and data transfer.
+there are industrial USB hubs, but they are bulky and very expensive.
+to solve this issue I decided to design my own USB hub, tailored to my needs.
+
+when developing and testing hardware, you often end with a lot of USB devices connected.
+USB allows to have up to 128 devices, but only with a maximum depth of 7.
+thus you are only allowed to have a maximum of 5 USB hubs between computer and devices, and I often have to plan my setup to not reach this limit.
+most 7-port USB hubs use two 4-port USB hub, the seconds being connected to the first.
+there are some exception to that, but they are rare, old, and often not advertised as such.
+this heavily limits the number of end devices.
+this device is a 7-port flat USB hub, preventing reaching this limit too often.
+
+the incoming and outgoing USB ports are individually ESD protected.
+this safety becomes important when developing, testing, and handling bare electronic devices.
+this also comes in handy against when connecting circuit with different ground potentials.
+ESD protections already saved my day twice.
+the issue is that they can blow without you noticing, but at least they protected the device once.
+
+each output port is current limited to 500 mA.
+no device should draw more that this specified limit.
+it if does, there is very probably an issue with the device.
+this protection allows to isolate the faulty device and not have it affect all other connected devices, or the hub itself.
+the fault is also detected and reported by the hub to the host computer.
+
+each output port is power controlled.
+this allows to remotely switch on an off individual devices.
+this is an important requirement when developing and testing devices, which require a power cycle.
+
+additionally, a switch next to the power can force the power off state.
+
+the USB hub can be self-powered (through the USB input port), externally powered by 5V, or externally powered by anything between 6 and 40V.
+this allows to use higher voltage power supplies to provide enough current to all power.
+the 5V are not feed back to the host.
+
+each output port comes with a high voltage output power port, connected to the high voltage input port.
+this allows to power devices which require more than 5V (e.g. 12V externally powered devices).
+each of these power output is controllable.
+as with the 5V USB power output, this allows to remotely switch on an off individual devices.
+
+each port has status LEDs, indicating the speed and power of the connected device.
+
+the board uses proper impedance and differential signal routing to provide clean USB transfer.
+
+design choice
+=============
+
+USB 3.0
+-------
+
+this hub is only for USB 2.0 devices.
+by far this are most of the devices I develop.
+is makes it simpler and keeps the cost reasonable.
+I often even disable USB 3.0 because of the 13-device limitation of the Intel xHCI.
+when I need USB 3.0 for the very few devices, I connected them to the computer directly.
+
+USB2517
+-------
+
+I wanted to use the FE2.1 7-port USB hub chip.
+it does not need an external voltage regulator or crystal.
+and it is easier to solder thanks to its TQFP package, and provides all required functionalities.
+sadly I could not find a source for the 64-pin packages, and the 48-pin variant does not provide all required functionalities.
+thus I had to fall back to the Microchip USB2517, which uses a harder to solder QFN package.
+
+current limitation
+------------------
+
+the few USB hubs that have current limitation on the output, use a MIC2026.
+this does limit the current to 500 mA, but only in constant current mode.
+the fault is reported (e.g. to the hub, back to the computer), but it is up to the user to power off the faulty device.
+instead I use poly-fuses, which automatically cut the power once the limit of 500 mA is reached.
+this is faster, and removes user-based actions.
+the fault is still reported.
+this is very useful when testing devices.
+
+LED color
+---------
+
+the USB specification, LEDs are used as port indicator (section 11.5.3)
+
+- off: powered off/disconnected
+- amber: current limitation reached
+- green: enabled or transmitting
+
+instead the following color scheme is used:
+
+- green off: power off or over-current
+- green on: power on
+- red: low speed device connected
+- blue: full speed device connected
+- purple (red+blue): high speed device connected
+- red and blue off: disconnected
+
 usage
 =====