README: document project and schematic

README.md

@@ -1,4 +1,4 @@
-This firmware template is designed for development boards based around [STM32 F4 series micro-controller](https://www.st.com/en/microcontrollers-microprocessors/stm32f4-series.html).
+firmware is for the I/O finder.
 
 project
 =======
@@ -6,31 +6,154 @@ project
 summary
 -------
 
-*describe project purpose*
+this tools allow to identify if channels (e.g. lines) are inputs or outputs.
+up to 16 channels can be identified at once.
+it also allows to monitor the channel activity.
+
+usage
+-----
+
+connect the pins or test points of the target device to the I/O finder channels pins on the connector.
+select the first and last channel to probe using the `start <CH>` ans `stop <CH>` commands.
+this prevents false activity monitoring alerts. 
+it will also make the scan faster.
+
+also connect the target voltage pin to the SWJ finder in order to use the right signal voltage level.
+alternatively, the SWJ finder can supply 3.3V to the target voltage pin using the `voltage 3` command.
+to revert to using the externally provided target voltage, use the `voltage 0` command.
+to measure the target voltage, use the `voltage` command.
+
+to find out what type of I/O is connected to the channel, use the `type` command.
+it will measure the voltage while applying a pull-up and pull-down.
+if the voltage changes, the channel is likely an input (or floating).
+it will also show what value of pull-up/down is already on the channel.
+if the voltage does not change, the channel is likely an output (or GND/power supply rail).
+be aware that this is just the result at the testing type, as the target can change its configuration.
+
+to monitor the activity of the channels, use the `monitor` command.
+provide to argument to not pull the channels.
+provide the 0 argument to pull the channels low using the internal 40 kOhm resistor.
+provide the 3 argument to pull the channels high to 3.3V using the internal 40 kOhm resistor.
+pulling the channels may reduce the noise, in case the channel is floating.
+the activity and current state (with time stamp) of the pin will be displayed in real time.
+if the channel is switch fast, a X will appear in from of the current level.
+to stop monitoring, press any key.
+
+you can also reset the target board if you connected to target reset pin to the SWJ finder.
+you can select of to drive the reset pin (OD for open-drain, PP for push-pull) and active level (H for high, L for low) using the `reset [ODL|ODH|PPL|PPH]` command.
+to assert or release the reset, us the `reset 1` or `reset 0` commands.
+alternatively, pressing/releasing the button on the SWJ finder asserts/releases the reset signal
+
+use the `help` command to list all commands.
+this will also list the shortcuts for the commands.
 
 technology
 ----------
 
-*described electronic details*
+to figure out the type of I/O a channel is, it:
+- selects the channel on a analog multiplexer
+- measures the voltage while applying a 2 kOhm pull-down (to ground)
+- measures the voltage while applying a 2 kOhm pull-up (to target voltage)
+- calculate the resistance on the channel (since it known the resistor values of the voltage divided used to measure the channel voltage)
+
+to monitor the activity, it directly reads the level of all 16 channels in parallel.
+no voltage shifter is used (the input have a high impedance to not affect the channels).
+any voltage above 3.3*0.7=2.3V is detected as high, else it is low.
+
+limitation
+----------
+
+the target voltage should not be higher than 5.5V (board I/O-pins limitation).
+the channel voltage level need to be above 2.3V for activity to be detected reliably.
+
+the reset pin has no inline protection resistor and can sink up to 25 mA.
+in open drain mode, an external pull-up resistor is required, most often provide by the target device.
+in push-pull mode it can only source 3.3V up to 25 mA.
 
 board
 =====
 
-The underlying template also supports following board:
-
-- [WeAct MiniF4](https://github.com/WeActTC/MiniF4-STM32F4x1), based on a STM32F401CCU6
-
-**Which board is used is defined in the Makefile**.
-This is required to map the user LED and button provided on the board
+the underlying hardware uses a [WeAct MiniF4](https://github.com/WeActTC/MiniF4-STM32F4x1) board, based on a STM32F401CCU6.
+the bi-directional level shifter are BSS138 n-channel MOSFET based.
+switching the target voltage are done using BSS84 p-channel MOSFET.
 
 connections
 ===========
 
-Connect the peripherals the following way (STM32F4xx signal; STM32F4xx pin; peripheral pin; peripheral signal; comment):
+remove LED on C13 on MiniF4 board so we can reuse the pin.
 
-- *list board to peripheral pin connections*
+IDC 2x10 connector:
 
-All pins are configured using `define`s in the corresponding source code.
+01. GND, connect to ground
+02. VTRG, target voltage, see below for connection
+03. RST, to reset the target board, connect to PA0
+04. 3V3, connected to 3.3V
+05. CH0, connect to PB12
+06. CH1, connect to PB13
+07. CH2, connect to PB14
+08. CH3, connect to PB15
+09. CH4, connect to PA8
+10. CH5, connect to PA9
+11. CH6, connect to PA10
+12. CH7, connect to PA15
+13. CH8, connect to PB3
+14. CH9, connect to PB4
+15. CH10, connect to PB5
+16. CH11, connect to PB6
+17. CH12, connect to PB7
+18. CH13, connect to PB8
+19. CH14, connect to PB9
+20. CH15, connect to PB10
+
+ADC, used to measure target voltage (up to 6.6V):
+
+- connect VTRG to 22 kOhm resistor R1
+- connect PA6 (ADC1_IN6) to other side of resistor R1
+- connect PA6 to 22 kOhm resistor R2
+- connect GND to other side of resistor R2, forming a voltage divided
+
+analog multiplexer, 16-channel, HP4067, to probe individual channels:
+
+- channels: C0-C15 to CH0-CH15
+- select: S3 to PB2, S2 to PB1, S1 to PB0, S0 to PA7
+- enable: EN to PC15, pulled up to VCC
+- signal: S to see below
+- VCC: to 5V (for better switching, the select line can still be operated at 3.3V)
+- GND: to ground
+
+ADC for signal, using BSS84 p-channel MOSFET Q5:
+
+- connect signal S to PA1/ADC1_IN1 through 1 KOhm resistor (first part of voltage divider)
+- connect 1 kOhm between PA1 and PA4, creating second part of voltage divider (PA4 can ground it)
+- Q5 source: to VTRG
+- Q5 gate: to PA5, pulled up to VTRG using 10-100 kOhm resistor
+- Q5 drain: to PA3 (PA4 can set connect voltage divider to high side)
+
+UART, with level shifter, to scan for UART port:
+
+- short PA3 (RX) and PA2 (TX), making it a half-duplex UART (sufficient for testing most UARTs)
+- connect PA2/PA3 to 150 Ohm in-line resistor R3 (used as protection to limit sink current)
+- pull up R3 to 5V using 10 kOhm ressitor, this is necessary for the voltage shifter to operate up to 5V
+- connect R3 to source of BSS138 n-channel MOSFET Q1, used as bi-directional level shifter
+- connect gate of Q1 to VTRG
+- connect source of Q1 to signal S
+
+level shifter control, using BSS84 p-channel MOSFET Q2:
+
+- gate: to PC14, pulled up to VTRG using 10-100 kOhm resistor
+- source: VTRG
+- drain: to signal S through 10 kOhm (this creates a pull-up resistor for the low side level shifter)
+
+target voltage supply control, using BSS84 p-channel MOSFET Q3 (to provide 3.3V) and BSS138 n-channel MOSFET Q4 (to prevent feed back into 3.3V):
+
+- Q3 gate: PC13, pulled up to 3.3V using 10-100 kOhm resistor
+- Q3 source: 3.3V
+- Q3 drain: Q4 source, 3.3V output for target
+- Q4 source: Q3 drain, forward 3.3V to target (through body diode and because gate is on)
+- Q4 gate: to 5V, enabling transition until 5V from target is present on drain
+- Q4 drain: VTRG
+
+all pins are configured using `define`s in the corresponding source code.
 
 code
 ====
@@ -86,4 +209,12 @@ To start the debugging session run `rake debug`.
 USB
 ---
 
-The firmware offers serial communication over USART1 and USB (using the CDC ACM device class).
+The firmware offers serial communication over USB (using the CDC ACM device class).
+
+TODO
+====
+
+add monitor single channel to support 1.8V voltage.
+measure frequency of single channel.
+decode single channel as RX.
+probe UART using TX than RX.