CuVoodoo STM32F1 firmware template
README.md
1 project
2 =======
3 
4 summary
5 -------
6 
7 This is the firmware for a digital clapperboard.
8 
9 technology
10 ----------
11 
12 Clapperboards are used to synchronize audio and video tracks by clapping two wooden pieces.
13 This is then visible on the video and the sharp sound is also present on the audio.
14 Using the scene and take number written on the clapperboard and announced at the beginning of the recording it is possible to know which sound track corresponds to which video track.
15 
16 This clapper board improves this system with some features:
17 
18 - use 7-segment displays to show number, instead of having to manually write and erase it on the board
19  - episode, scene, and take
20  - two audio and video track numbers (number used in the file names or the recordings)
21  - current date, time, and frame number
22 - automatically increment the take and recording numbers
23 
24 The numbers on the board can be adjusted by hand using buttons.
25 
26 board
27 =====
28 
29 The current implementation uses a [core board](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#core_board).
30 The underlying [template](https://git.cuvoodoo.info/stm32f1/about/) supports additional board.
31 
32 peripherals
33 ===========
34 
35 - 1x 8-digit 7-segment display based on the MAX7219 to display the date
36 - 1x 8-digit 7-segment display based on the MAX7219 to display the time (hours, minutes, seconds) and frame number
37 - 7x 4-digit 7-segment display based on the TM1637 to display recording information
38  - 1x to display the episode (or chapter)
39  - 1x to display the scene
40  - 1x to display the take
41  - 2x to display the video file number
42  - 2x to display the audio file number
43 - 1x 16-channel multiplexer to communicate with the 7-segments individually
44 - 8x2 button switches to adjust the recording numbers and seconds
45 - 1x button switch to detect clap
46 - 1x shake sensor to detect movement and switch on the clapper board
47 - 1x DS1307 RTC to keep track of the time (using a tiny RTC module)
48 - 1x I2C EEPROM to save numbers (also present on the tiny RTC module)
49 - 1x power switching board (to switch off power completely)
50 - 1x battery + protection, charge, and 5V step up circuit
51 
52 connections
53 ===========
54 
55 Connect the peripherals the following way (peripheral signal; peripheral pin; micro-controller pin; micro-controller signal; comment):
56 
57 - DS1307 RTC to get the date and EEPROM to save the numbers
58  - VCC; 8; ; +5V;
59  - GND; 4; ; GND;
60  - SCL; 6; PB10; I2C2_SCL;
61  - SDA; 5; PB11; I2C2_SDA;
62  - SQW; 7; PBO; GPIO; to synchronize the seconds
63 - 2x MAX7219 in chain to show date and time
64  - VCC; 19; ; +5V;
65  - GND; 4; ; GND;
66  - CLK; 13; PB13; SPI2_CLK;
67  - DIN; 1; PB15; SPI2_MOSI;
68  - LOAD; 12; PB12; SPI2_NSS; used as GPIO
69 - 7x TM1637 to show the recording numbers
70  - VDD; 16; ; +5V;
71  - GND; 1; ; GND;
72  - DIO; 17; PB7; GPIO; display with no clock signal will ignore data activity
73  - CLK; 18; 3-9; I0-I6; on analog multiplexer
74 - 1x CD74HC4067 16-channel multiplexer
75  - VCC; 24; ; +5V;
76  - GND; 12; ; GND;
77  - common input; 1; PB6; GPIO; clock for TM1637
78  - -E; 15; PB9; GPIO; to enable on low
79  - S0; 10; PB3; GPIO; to select output
80  - S1; 11; PB4; GPIO; to select output
81  - S2; 14; PB5; GPIO; to select output
82  - S3; 13; ; GND;
83  - I0; 9; 18; CLK; TM1637 for audio 2
84  - I1; 8; 18; CLK; TM1637 for video 2
85  - I2; 7; 18; CLK; TM1637 for audio 1
86  - I3; 6; 18; CLK; TM1637 for video 1
87  - I4; 5; 18; CLK; TM1637 for episode
88  - I5; 4; 18; CLK; TM1637 for scene
89  - I6; 3; 18; CLK; TM1637 for take
90 - 1x power board (custom), including SW-18015P shake switch between collector of PNP and emitter (with pull-down resistor and diode between shake switch and emitter)
91  - GND; ; GND; step up voltage regulator;
92  - IN; ; 5V; step up voltage regulator;
93  - OUT; ; +5V; all other peripherals
94  - base of PNP; SWITCH; PB8; to control power to all peripherals
95  - not-collector connected pin of shake switch; ACTIVITY; PB1; to detect power-up activity
96 - 1x clap switch
97  - pin 1; 1; ; GND;
98  - pin 2; 2; PB14; ; to detect clapping action (add pull-up resistor to improve detection)
99 - 16x buttons, in a 4x4 matrix
100  - 4x row 0 buttons; ; PA0; ; row 0
101  - 4x row 1 buttons; ; PA1; ; row 1
102  - 4x row 2 buttons; ; PA2; ; row 2
103  - 4x row 3 buttons; ; PA3; ; row 3
104  - 4x column 0 buttons; ; PA4; ; column 0, with a pull-down resistor
105  - 4x column 1 buttons; ; PA5; ; column 1, with a pull-down resistor
106  - 4x column 2 buttons; ; PA6; ; column 2, with a pull-down resistor
107  - 4x column 3 buttons; ; PA15; ; column 3, with a pull-down resistor
108 
109 All pins are configured using `define`s in the corresponding source code.
110 
111 code
112 ====
113 
114 dependencies
115 ------------
116 
117 The source code uses the [libopencm3](http://libopencm3.org/) library.
118 The projects is already a git submodules.
119 To initialize and it you just need to run once: `git submodule init` and `git submodule update`.
120 
121 firmware
122 --------
123 
124 To compile the firmware run `make`.
125 
126 documentation
127 -------------
128 
129 To generate doxygen documentation run `make doc`.
130 
131 flash
132 -----
133 
134 The firmware will be flashed using SWD (Serial Wire Debug).
135 For that you need an SWD adapter.
136 The `Makefile` uses a ST-Link V2 along OpenOCD software (per default), or a Black Magic Probe.
137 To flash using SWD run `make flash`.
138 
139 debug
140 -----
141 
142 SWD also allows to debug the code running on the micro-controller using GDB.
143 To start the debugging session run `make debug`.
144 
145 USB
146 ---
147 
148 The firmware offers serial communication over USART1 and USB (using the CDC ACM device class).
149 Date and time can be set over serial.
150 
151 You can also reset the board by setting the serial width to 5 bits over USB.
152 To reset the board run `make reset`.
153 This only works if the USB CDC ACM is running correctly and the micro-controller isn't stuck.