Move all documentation to this repo

README.md

@@ -1,2 +1,26 @@
-# docs
+# Instructions
+[Hardware assembly](hardware/index.md)
+
+[Build and install firmware](firmware.md)
+
+# Features
+
+* Web interface
+* Buttons
+* LEDs
+* Screens
+  * Block height
+  * Moscow Time (Sats per Dollar)
+  * Price
+  * Time
+  * Halving Countdown
+  * Block Fee Rate*
+  * Market Cap*
+  * BitAxe hashrate and best difficulty*
+  * Nostr Zap Notifications*
+
+*: Added in v3 Firmware
+
+Through mDNS protocol, the webinterface should be accessible using http://btclock3.local or just http://btclock3.
+
 

firmware.md

@@ -0,0 +1,59 @@
+## Web installer
+
+You can now install the BTClock firmware directly from your browser (only Chrome/Chromium and Microsoft Edge for now) using https://btclock.store/web-flasher/
+
+The first time you have to put the S3 mini in to boot mode:
+Press both buttons at the same time (RST/BOOT), then first release the RST button and then the boot button.
+
+## Build and compile
+
+**NOTE**: The instructions below are for V2, V3 is available and highly recommended over V2. We will update the instructions soon.
+
+To do this we need [Visual Studio Code](https://code.visualstudio.com/Download), [node.js](https://nodejs.org/en/download) and [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#windows-stable). 
+
+Also you will need the [PlatformIO IDE for Visual Studio Code](https://platformio.org/install/ide?install=vscode)
+
+Please follow the installation instructions before you continue. 
+
+When you successfully installed VSC (Visual Studio Code) follow the following steps to upload the code to the Wemos S3 Mini.
+
+<img src="media/VSC_1.png" width="500"/>
+
+Add the repository from GitHub <https://git.btclock.dev/btclock/btclock_v3> to VSC 
+
+<img src="media/VSC_2.png" width="500"/>
+
+When you put in the URL just click on the button that appears (btclock/btclock_v3).
+
+<img src="media/VSC_3.png" width="500"/>
+
+Select a repository directory and click "Select as Repository Destination" and click on open. Note: it can take some time to load all the necessary data. Please wait.
+
+<img src="media/VSC_5.png" width="500"/>
+
+After all the data is loaded, click on PlatformIO (in the right standing menu)
+Then select the correct environment by "Switch PlatformIO Project Environment" in the under menu:
+
+- `env:lolin_s3_mini_213epd` for a Rev. A board with 2.13 inch ePaper screens
+- `env:lolin_s3_mini_29epd` for a Rev. A board with 2.9 inch ePaper screens (unsupported)
+- `env:btclock_rev_b_213epd` for a Rev. B board with 2.13 inch ePaper screens
+
+
+<img src="media/VSC_6.png" width="500"/>
+
+Now it's time to build the software. Expand the "General" and "Platform" menu and click on "Build" and "Build Filesystem image" (one at the time) After building is complete first connect your Wemos S3 Mini or Rev. B board by an USB-C data cable to your computer and put it in to boot mode, to put it in to boot mode you have to push both buttons on the S3 Mini or Rev. B board at the same time, but when releasing you have to release the reset button first. 
+
+When the board is in boot mode first upload the filesystem image by clicking "Upload Filesystem Image" after completing click under "General" "Upload". When complete your clock shut show you something like this
+
+<img src="media/IMG_2179.jpeg" width="500"/>
+
+Scan the QR-code with your smartphone and establish the WiFi connection. When the WiFi connection is established, open a web browser and type the following in the search bar "192.168.4.1". Since this is a captive portal, your device might automatically take you to this page already.
+You will get a page like screenshot 1.
+
+<img src="media/IMG_2181.jpeg" width="180"/> <img src="media/IMG_2183.jpeg" width="180"/> <img src="media/IMG_2184.jpeg" width="180"/>
+
+Click on "Configure WiFi" and select the your WiFi SSID and add the necessary credentials. After you click have click on "save" you should get the screen like screenshot 3 and the clock will show you this or some of the other screens.
+
+<img src="media/IMG_2185.jpeg" width="500"/>
+
+Make sure all displays work, before completing the clock in the last step.

hardware/index.md

@@ -0,0 +1,3 @@
+[Rev. A instructions](rev_a.md)
+
+[Rev. B instructions](rev_b.md)

hardware/rev_a.md

@@ -0,0 +1,143 @@
+# Parts list
+
+| **#** 	| **Part**                           	| **Amount** 	| **Optional** 	| **Remarks**                                          	|
+|-------	|------------------------------------	|------------	|--------------	|------------------------------------------------------	|
+| 1     	| Main PCB                           	| 1          	|              	|                                                      	|
+| 2     	| Front PCB                          	| 1          	| Yes          	|                                                      	|
+| 3     	| Acryl front and back               	| 1          	| Yes          	|                                                      	|
+| 4     	| WeAct 2.13 inch B/W ePaper display 	| 7          	|              	| Buy at [AliExpress](https://www.aliexpress.com/item/1005004644515880.html?pdp_ext_f=%7B%22sku_id%22%3A%2212000031468032209%22%7D)<br>Make sure you select the right version 2.13-Black-White! B/W/R is not usable.	|
+| 5     	| 2x4pin 2.54mm Female Header        	| 7          	|              	| Included in required components set                  	|
+| 6     	| Wemos S3 Mini                      	| 1          	|              	| Buy at [Tinytronics (Dutch webshop)](https://www.tinytronics.nl/shop/nl/development-boards/microcontroller-boards/met-wi-fi/wemos-s3-mini-esp32-s3-v1.0.0)<br>Buy at [AliExpress](https://www.aliexpress.com/item/1005005449219195.html?)  	|
+| 7     	| 3pin 2.54mmm Male header           	| 3          	|              	| Included in required components set                  	|
+| 8     	| 2.54mm Female Jumper               	| 3          	|              	| Included in required components set                  	|
+| 9     	| 100nF SMD capacitor 0805           	| 6          	|              	| Included in required components set                  	|
+| 10    	| MCP23017-E/SP                      	| 1          	|              	| Included in required components set                  	|
+| 11    	| 12x12x7.3mm tactile push button    	| 5          	|              	| Included in required components set                  	|
+| 12    	| 12x12 round button cap             	| 5          	|              	| Included in required components set                  	|
+| 13    	| Resistor 4.7k ohm                  	| 2          	|              	| Included in required components set                  	|
+| 14    	| Resistor 10k ohm                   	| 1          	|              	| Included in required components set                  	|
+| 15    	| 10 pin Resistor Array 10k ohm      	| 1          	|              	| Included in required components set                  	|
+| 16    	| USB-C 2-pin port                   	| 1          	| Yes          	| Included in required components set                  	|
+| 17    	| WS2812B 5050 LEDs                  	| 4          	|              	| Included in required components set                  	|
+| 18    	| M3x6x1 spacer (washer)              	| 28         	|              	| Included in screw set                                	|
+| 19    	| M3x6 standoff M-F                  	| 4          	|              	| Included in screw set                                	|
+| 20    	| M3x6 screw                         	| 56         	|              	| Included in screw set                                	|
+| 21    	| M3x8 standoff M-F                  	| 8          	|              	| Included in screw set                                	|
+| 22    	| M3x10 standoff F-F                 	| 28         	|              	| Included in screw set                                	|
+| 23    	| M3x12 standoff F-F                 	| 2         	|              	| Included in screw set                                    |
+| 24    	| M3x10 screw                        	| 4          	|              	| Included in screw set                                	|
+| 25    	| M3 nut                             	| 2          	|              	| Included in screw set                                	|
+| 26    	| 1N4001 diode                        	| 1          	|              	| Included in required components set (since V.1-23)                               	|
+---
+
+# Board revisions
+
+| PCB Version 	| Version blockhash                                                	| Changelog   	|
+|-------------	|------------------------------------------------------------------	|---	|
+| V.1-22      	| [0000000000000000000540c807c73e5a4ba24284ee351d287978e324a786dae3](https://mempool.space/block/0000000000000000000540c807c73e5a4ba24284ee351d287978e324a786dae3) 	|   	|
+| V.1-23      	| [00000000000000000001ac31d136df6577f457e683e8b98b03d628840a1d3b4c](https://mempool.space/block/00000000000000000001ac31d136df6577f457e683e8b98b03d628840a1d3b4c) 	| Added diode for reverse polarity protection   	|
+| V.1-40        | [00000000000000000001b035d353d599df6fa46122c07cf2036ae9959669a4b2](https://mempool.space/block/00000000000000000001b035d353d599df6fa46122c07cf2036ae9959669a4b2)  | Greater holes for diode and placement marking R1 |
+
+![Board](../media/IMG_2143.jpeg)
+
+# Building instructions
+
+This instruction will guide you through the building process. Please read carefully before you start building, some parts have polarity, keep this in mind during the process.
+
+## Solder SMD components
+
+*Note*: The bare PCB without SMD components isn't sold anymore since november 2023. 
+You might still have the SMD components in the plastic box, but you don't need them.
+
+<img src="../media/IMG_2158.jpeg" width="500"/>
+<img src="../media/IMG_2159.jpeg" width="500"/>
+
+First step is to solder the SMD capacitors on the front and back of the main PCB. (C1 t/m C6)
+
+<img src="../media/IMG_2161.jpeg" width="500"/>
+
+Next will be the LED’s (WS2812B) **WARNING** this component has polarity! The white triangle has to be in the lower right corner!
+
+<img src="../media/overview-diode-resistors.jpeg" width="500"/>
+
+## Solder through hole components
+
+Now it’s time for the resistors. **WARNING** R1 has polarity! Pin one (marked with a dot) should be at the side with the diagonal corner, next to the jumpers.
+The other resistors don’t have polarity but have different values, R2/R3 are 4K7 and R4 is 10K.
+
+![IMG_1451](https://github.com/dsbaars/btclock_v2/assets/480514/ffbec8f4-3d6e-4fda-b9e8-59acebc343f5)
+
+You can choose to use a precision IC-mount (not included in the kit) or solder the MCP23017 directly to the PCB. We prefer an IC-mount so if you need to change the IC in the future it’s an easy job, the choice is yours ;) 
+If you choose to use an IC-mount note that it has polarity! The MCP23017 has polarity as well, the dot on the main PCB notes for pin 1, the must be corresponding with the dot on the MCP23017.
+
+<img src="../media/diode-marking.jpeg" height="250"/>
+
+Next up is the 1N4001 diode, **WARNING** the diode also has polarity. Align the line on the 1N4001 with the line on the PCB.
+
+If you ordered a pre-soldered PCB you might not have a diode. This is not a problem since it is just a protection against reverse polarity of the extra USB port. The pre-soldered PCBs are tested for this.
+
+<img src="../media/overview-diode-resistors.jpeg" width="500"/>
+
+When placed correctly it should look like this:
+
+<img src="../media/IMG_2167.jpeg" width="248" height="170"/> <img src="../media/IMG_2168.jpeg" width="248" height="170"/>
+
+<span style="color: red !important;">**Recommended:**</span> Test the Wemos S3 Mini on your computer before soldering it on the board to rule out a possible DOA. You might need to put the S3 Mini in boot-mode before it is recognized for the first time.
+
+We recommended to use 2x8 2,54 male headers instead of 2 1x8 2,54 male headers on both sides of the Wemos S3 mini. This makes soldering the Wemos S3 Mini on the main PCB much easier (Please note that double headers are not included in the kit).
+
+<img src="../media/IMG_2170.jpeg" width="500"/>
+
+Now it’s time to solder the 2x4 2,54 female headers like the picture above. Also the 1x3 2,54 male headers can be placed, above the MCP2307 see picture below. The jumpers had to be placed in the down position, as close to the MCP23017
+
+<img src="../media/PL1-3.png" width="500"/>
+
+If you had chosen to use an IC-mount it’s time to place the MCP23017 remember that the MCP23017 has polarity, the dot on the main PCB must be corresponding to the dot on the MCP23017
+
+<img src="../media/usb-polarity.jpeg" width="250"/>
+
+Solder the USB-C port, do not bend any of the pins. The USB-C port from the kit fits only with the correct polarity. 
+
+<img src="../media/IMG_2174.jpeg" width="500"/>
+
+Last but not least now the buttons can be mounted to the main PCB.
+
+<img src="../media/IMG_2172.jpeg" width="500"/>
+
+Now it's time to solder the 2X4 2.54 male headers to the e-Ink displays. The choice is yours whether you want to use the yellow ones or choose to use black headers. In our opinion it is more pleasant to choose the black one because most of the parts are black.
+
+<img src="../media/IMG_2175.jpeg" width="500"/>
+
+You have done it; all parts are on the main PCB now! Before we continue to build the clock together we first want to test the displays, so it's time to upload the software to the Wemos S3 Mini. See the [build and install firmware wiki-page](Build-and-install-firmware)
+
+## Place screws and standoffs
+
+First, disassemble the displays and place all the 10mm female - female standoffs at the front of the main PCB with the 6mm screws. Keep in mind that at te corners at the back you have to use the 8mm female - male standoffs, this also applies to the middle 2 at the top of the back. 
+
+At the bottom of the middle 2 you also have to use the 8mm female - male standoffs but these ones need a nut. Place on each 10mm standoff on the top of the standoffs an 1mm washer, place the displays on the top of them and mount them with the 6mm screws.
+
+Keep in mind that at the corners on the top of the first (left corner) and last (right corner) display you don't use a screw, this is where the screw come to mount the front pcb in combination with acrylic front. 
+
+![BTClock Screw Legend](https://github.com/dsbaars/btclock_v2/assets/480514/652e9572-4fb7-4b80-b3b6-4cb20246ca57)
+
+<img src="../media/IMG_2255.jpeg" width="500"/>
+
+<img src="../media/IMG_2256.jpeg" width="500"/>
+
+<img src="../media/IMG_2257.jpeg" width="500"/>
+
+## Pre-soldered everything version
+
+If you have the pre-soldered everything version, you only need to solder the Wemos S3 Mini.
+
+<img src="../media/IMG_2170.jpeg" width="500"/>
+
+And then you can test the ePaper displays.
+
+## Complete assembly
+
+First fasten the acrylic back with 8x M3x6mm screws, after that you fasten Front PCB in combination with acrylic front with the 4x M3x8mm screws. Note that at the bottom corners you have to use an extra 1mm washer.
+
+After that your clock should look like this
+
+<img src="../media/IMG_2143.jpeg" width="500"/>

hardware/rev_b.md

@@ -0,0 +1,46 @@
+# Rev.B (With or without front light)
+
+<img src="../media/Rev.B/IMG_3310.jpeg" width="750"/>
+
+# Parts list
+
+| **#** 	| **Part**                           	| **Amount** 	| **Optional** 	| **Remarks**                                          	|
+|-------	|------------------------------------	|------------	|--------------	|------------------------------------------------------	|
+| 1.     	| Main PCB                           	| 1          	|              	|                                                      	|
+| 2.     	| 2.13 inch B/W ePaper display 	| 7          	|              	| WeAct 2.13-Black-White or included in some kits. <br>Buy at [AliExpress](https://www.aliexpress.com/item/1005004644515880.html?pdp_ext_f=%7B%22sku_id%22%3A%2212000031468032209%22%7D)<br>Make sure you select the right version 2.13-Black-White! B/W/R is not usable.	|
+| 3.     	| Front PCB                     	| 1          	| Yes          	|                                                      	|
+| 4.     	| Acryl front and back               	| 1          	| Yes          	|                                                      	|
+| 5.     	| M3x6 standoff M-F                  	| 4          	|              	| Included in screw set                                	|
+| 6.      	| M3x6 screw                         	| 54         	|              	| Included in screw set                                	|
+| 7.     	| M3x8 standoff M-F                  	| 8          	|              	| Included in screw set                                	|
+| 8.     	| M3x11 standoff F-F                 	| 28         	|              	| Included in screw set                                	|
+| 9.     	| M3x12 standoff F-F                 	| 2         	|              	| Included in screw set                                    |
+| 10.    	| M3x10 screw                        	| 4          	|              	| Included in screw set                                	|
+---
+
+# Board revisions
+
+| PCB Version 	| Version blockhash                                                	| Changelog   	|
+|-------------	|------------------------------------------------------------------	|---	|
+| Rev.B-01      	| [000000000000000000014684133a4d63ab75f40ea0ece278157521dd983eadf7](https://mempool.space/block/000000000000000000014684133a4d63ab75f40ea0ece278157521dd983eadf7) 	| First Beta  	|
+| Rev.B-02      	| [00000000000000000003509af203f00a74cada8024e017982fe9c499751f36de](https://mempool.space/block/00000000000000000003509af203f00a74cada8024e017982fe9c499751f36de) 	| Second Beta   |
+| Rev.B-03        | [000000000000000000008dfc59d82518a12888f17fb0213fe0db8102afffe0cd](https://mempool.space/block/000000000000000000008dfc59d82518a12888f17fb0213fe0db8102afffe0cd)  | Final Version |
+
+# Hardware assembly (Place screws and standoffs)
+
+<img src="../media/Rev.B/IMG_3314.jpeg" width="750"/>
+<img src="../media/Rev.B/IMG_3313.jpeg" width="750"/>
+
+First, place all the 11mm female - female standoffs (Orange) at the front of the main PCB with the 6mm screws. Keep in mind that at te top-corners at the back you have to use the 8mm female - male standoffs, this also applies to the, one out-of-the middle 2 at the top of the back. At the bottom of the, one out-of-the middle 2 you also have to use the 8mm female - male standoffs (Green).
+
+Mount the two M3x12 standoff F-F (Yellow) at the front with the last two of the M3x8 standoff M-F (Green)
+
+Place the displays on the top of the 11mm standoffs and mount them with the 6mm screws.
+
+<img src="../media/Rev.B/IMG_3317.jpeg" width="750"/>
+
+Keep in mind that at the corners on the top of the first (left corner) and last (right corner) display you don't use a screw, this is where a 6mm standoff has to placed to screw the front pcb in combination with acrylic front. For mounting the fromt pcb with the acrylic front use the M3x10 screw.
+
+<img src="../media/Rev.B/IMG_3310.jpeg" width="750"/>
+
+At last, place the acrylic back on the back with the last 8 M3x6 screws.