Merge pull request #11 from WMTaylor3/docs/refactor-documentation

Additions to and refactors of documentation

Code/README.md

@@ -0,0 +1,18 @@
+# Code
+## Overview
+This project was developed using VSCode with the PlatformIO plugin for the ESP32. This is essentially Arduino/C++ code so if you have experience with either of those you'll be able to jump right in. Feel free to make modifications and improvements, however, I would ask you raise a PR to have them pulled back into this repo for everyones benefit.
+
+## Getting Started Developing
+You can ignore this section if you have experience with PlatformIO or have your own way in which you develop code and deploy for the ESP32.
+
+Otherwise you'll need to download and install VSCode for your system, then head to the extensions tab on the left and install the PlatformIO plug in.
+
+With the extension installed, click the new PlatformIO icon on the left toolbar, `Open Project` and point it to this `Code` folder. It's important you point to this folder and not the root of the repo otherwise PlatformIO won't be able to find it.
+
+From there, you should be pretty much ready to go, the settings are preconfigured for a generic ESP32 so plug one into your system and head to the `src/main.cpp` file. In the top right of the window you'll see a tick icon to verify the sketch and next to it a drop down arrow which will give you the option to deploy.
+
+## Deploying
+This section assumes you've got a means by which to deploy code to an ESP32. In which case you'll find what you need in the `src` directory of this folder. Before deploying, remember to update the `arduino_secrets.h` file to include the name of your WiFi.
+
+## Sensitive Information
+Sensitive information such as Wi-Fi names and password etc are all stored in a secrets file `arduino_secrets.h`. This hasn't been uploaded for obvious reasons, but a sample file is present to show the formatting. Update as needed and remove the `-sample` suffix.

Docs/COMPONENT.md

@@ -0,0 +1,94 @@
+# Parts List
+The below components list is targeted towards the PCB revision that makes use of an external battery bank such as the BlackVue B-130X. Notes are provided which specify any additions or removals for the non-battery version.
+
+## Dash-cam Only
+* [BlackVue B-130X](https://www.blackvue.com.au/accessories/blackvue-b-130x/)
+
+* Can substitute this for a different battery pack which is capable of charging at alternator voltage and outputs both 12V and 5V.
+
+* You may be tempted, as I was, to just wire a second 12V battery straight in here. But there are some issues with that:
+
+* You can't just wire a 12V lithium battery to your cars accessory circuit. You'll probably blow it up. Lithium batteries require a specific charging circuit which is different from the lead-acid optimized versions used in most cars.
+
+* You **can** wire in another lead acid battery to your car (ideally a deep cycle one for this use case) but there are considerations to take. For example, you can't just wire it into the cabin using a fuse-tap as the amount of current it will pull while charging will likely blow the fuse. Also you don't want it in the cabin anyway as those things can leak fumes while charging. Finally, you need to be careful just wiring a battery in parallel with your cars accessory power as (while it will charge when the car is on) it will also push power back into the car when you turn the car off, leaving accessories powered in the car as possibly causing damage.
+
+* All of the above is why, though it's more expensive than just a 7Ah Deep Cycle battery, I went with something off the shelf.
+
+* The PCB itself. You'll find the Gerber files in this repo. Just place an order with JLCPCB or PCBWay and have them manufacture it for you. Default settings are fine.
+
+* 1x [EzSBC ESP32](https://ezsbc.shop/products/esp32-breakout-and-development-board)
+
+* Other ESP32 units will work from a software standpoint. But the PCB is designed to fit one of these units specifically. I recommend them as they are well made, they offer good after-sales support and they have the lowest deep-sleep current of any ESP32 I've found.
+
+* 1x [HFD2/005-M-L2](https://www.ebay.com/itm/126486144962))
+
+* I just got mine off EBay. Knock-offs but they work.
+
+* HFD2 is the component ID. Not interchangeable here.
+
+* 005 indicates it's the version operated off 5V control (as opposed to the "012" 12V version etc). Not interchangeable here.
+
+* M indicates it's the standard sensitivity version. The "S" sensitive version will likely work here too as a substitute.
+
+* L2 indicates it's two coil control rather than a single coil with reverse polarity. Not interchangeable here.
+
+* 1x [JD1914 Relay](https://www.ebay.com/itm/235041567706)
+
+* Again, I went EBay here.
+
+* Harness not required, the board is designed to accept it directly.
+
+* Any automotive relay that fits the footprint works. Automotive ideally as the coil here is controlled from the cars accessory power so will need to handle the associated voltage range.
+
+* 2x [2N2222 Transistor](https://www.ebay.com/itm/123551520883)
+
+* 3x [1N4007 Diode](https://www.ebay.com/itm/304657829012)
+
+* 3x [10k Resistor](https://www.ebay.com/itm/255227417575)
+
+* 2x [1k Resistor](https://www.ebay.com/itm/255227383471)
+
+* 1x [JST-VH 3.96mm Pitch 8-Pin Connector](https://www.ebay.com/itm/363949222192)
+
+* 2x [JST-VH 3.96mm Pitch 2-Pin Connector](https://www.ebay.com/itm/204070036118)
+
+* 1x [JST-VH 3.96mm Pitch 3-Pin Connector](https://www.ebay.com/itm/363948017305)
+
+### Non External Battery Version
+Add/Remove the following to make use of the no-external-battery version of the PCB.
+
+**Remove**
+
+* 1x BlackVue B-130X
+
+* 1x JST-VH 3.96mm Pitch 8-Pin Connector
+
+**Add**
+
+* 1x [JST-VH 3.96mm Pitch 2-Pin Connector](https://www.ebay.com/itm/204070036118)
+
+* 1x [XL4015 Step-Down Buck Converter](https://www.ebay.com/itm/162483771195)
+
+* Form factors for this vary, find one that measures 24mm x 54mm.
+
+* 2x [Fuse Taps](https://www.ebay.com/itm/374685769343)
+
+* These come in different sizes so find the one appropriate for your car. Here we need one for connecting the cars Acc line and the other for its Const line. You will also need a means to connect to the earth of your car, often you can get away with screwing a wire to an unpainted metal point on the chassis.
+
+* The BlackVue battery bank has all of these included, hence them being listed separately here.
+
+## Add GPS Tracker
+Dash-cam items listed above, plus:
+
+* 1x [JST-VH 3.96mm Pitch 3-Pin Connector](https://www.ebay.com/itm/363948017305)
+
+* 1x 12V 4G Tracker of your choice. Personally I went with the [Miktrack MT600](https://shop.mictrack.com/product/4g-vehicle-gps-tracker-mt600/) and have no complaints.
+
+## Add 4G Wi-Fi
+Dash-cam items listed above, plus:
+
+* 1x [JST-VH 3.96mm Pitch 2-Pin Connector](https://www.ebay.com/itm/204070036118)
+
+* 1x Sacrifical USB extension cable, or any cable with a female USB-A connector.
+
+* 1x 5V 4G Wi-Fi dongle of your choice. Personally I went with the [Huawei E8372](https://consumer.huawei.com/in/routers/e8372/) and it works well enough.

Docs/OPERATION.md

@@ -0,0 +1,27 @@
+# Operation
+For using the device once it's been installed
+
+## Standard Behavior
+### Tracker
+Addition of a GPS tracker to this project is optional. If desired, one can be connected by way of the "Tracker" header on the PCB. If supplied, the tracker will receive power from the external battery at all times, regardless of the car being at home, away, driving or stopped. Generally these trackers are designed to use minimal amounts of power and so cause negligible drain on the external battery. For more information on integrating a tracker with this project, refer to the [TRACKER.md](Tracker) documentation.
+
+### 5V Output
+A switched 5V output is also supplied as part of this project by way of the 2 pin header labelled 5V. This output is supplied from the external battery provided there is something connected to the 5V header. (Note, if using the PCB revision intended for use without an additional battery, this 5V output is supplied by way of a 12V to 5V converter drawing power from the cars own battery). The output to this header is switched on and off in sync with the 12V output to the dash cam. A potential use for this output (and the one I intend to implement) is to power a USB 4G to WiFi dongle. This will ensure that whenever the dash-cam has power, it also has internet connectivity for remote access.
+
+### Dash-Cam
+Once the system has been installed, standard behavior is as follows:
+
+* When the car is switched on, the dash-cam will receive power on both **Const** and **Acc** lines, in most dash-cams will cause it to enter standard recording mode as it normally would while driving.
+
+* When the car is parked and the engine switched off, the ESP32 and the dash-cam will lose **Acc** power, causing the camera to enter "Parking Mode" (if it supports it). At the same time, the ESP32 will begin searching for the home WiFi network.
+
+* If it is unable to find it within 2.5 minutes, it will leave power supplied from the external battery pack to the dash-cams **Const** input, allowing it to remain in parking mode for as long as the external battery has power. The ESP32 will then enter deep sleep.
+
+* If the ESP32 is able to locate the home WiFi within the 2.5 minute search interval, it will cut **Const** power to the dash-cam from the external battery pack, causing the camera to shut down completely. It will then enter deep sleep.
+
+* When the car is switched on again, the ESP32 will awaken from deep sleep and restore **Const** power to the dash-cam if it was previously disconnected, at the same time the dash-cam will receive **Acc** power, causing it to enter standard recording mode.
+
+* During the time the car is driving, the external battery pack will be charged.
+
+## Bluetooth Control
+TODO: Document Bluetooth commands when they are finalized.

Docs/SCENARIO.md

@@ -0,0 +1,74 @@
+# Scenario
+I have a dash cam in my car, one with cameras both front and rear. Out of the box, there are a few options of how to power this, each with its own issues.
+
+1) Wire camera to cars accessory power.
+
+   * Cameras run while vehicle is on.
+
+   * Avoids draining the vehicle battery while it's parked.
+
+   * Will only record accidents that occur while the car is driving, leaving it vulnerable while parked in public.
+
+2) Wire camera to cars constant power.
+
+   * Records for as long as the car battery has sufficient power.
+
+   * Will run down car battery if vehicle is not driven frequently for sufficient duration.
+
+   * Some cameras have low voltage cut off settings so you can program them to monitor the car battery and switch off when it gets to a certain level (e.g. 12V).
+
+This has the advantage of ensuring the battery never drops so low that the engine won't start, however it does still cause some undesired battery cycling constantly moving it between [low-cut-off-voltage] and >14V.
+
+Also means that if the cut off voltage is reached, the camera will power down and stop recording. Rendering it a bit useless until the car is driven again.
+
+3) Make use of dash-cam battery pack, such as the BlackVue B-130X.
+
+   * Similar to 2 but with the advantage of not causing any wear or drain on the car battery.
+
+
+Option 1 doesn't work for me, cause I've been hit while parked several times. So how about 2 & 3?
+
+
+The issue with numbers 2 & 3 is best told in the form of the delightful children's fable "Jeff, Julie, and the Dash-cam":
+
+* Jeff works out that with his alternator output, battery health and camera consumption, for every 10 mins spent driving, he charges his battery enough to run the camera for 3 hours.
+
+* Jeff drives into work, where he parks his car in the staff car park for 8 hours a day.
+
+* Jeff's commute is 20 mins each way.
+
+In Jeff's case, he's going to generate enough power on his drive to work to run his camera for only 6 of the 8 hours he's parked in his staff parking lot. Then he's going to drive 20 minutes back home at the end of the day and park his car in the garage. The power he put into the battery on his drive home will be wasted overnight, powering his dash-cam as it records the inside of his garage for 6 hours. Even worse, he's starting from scratch again with his 20 minute drive to work the next day. And so the cycle of Jeff's life continues.
+
+One day, while driving home from work, Jeff thinks "If I could find a way of having my dash-cam **not** record while it's parked safely overnight in my garage, I would build up 6 hours worth of battery on the drive home, and **another** 6 hours worth of battery on my drive to work the next day. That's more than enough to cover my entire work day **and** it leaves me operating at a surplus! Jeff tells his wife, Julie, about his brainwave. It doesn't seem to do anything for her so while he's back to square 1 in the "wooing Julie" department, he at least has a plan for his dash-cam.
+
+For some, the simple answer would be "just unplug the dash cam when you get home, plug it in again when you leave". And while that works, Jeff has two problems.
+
+1) He's lazy and can't be bothered doing that.
+
+2) Julie. She's not the sharpest tooth in the hens mouth and can't be trusted to plug and unplug the dash-cam as needed.
+
+So something else is needed...
+
+The solution is basically as follows:
+
+* Use a dash-cam battery pack such as the B-130X. This keeps the car battery safe no matter what.
+
+* Using an ESP32 powered off the battery pack conditionally open or close a relay between the battery pack output and the dash-cam.
+
+* The ESP will be able to sense when the car accessory power is turned on and off.
+
+* When the car is turned off, the ESP will search for 3 minutes for the name of the users home WiFi network.
+
+* If the WiFi is found, assume the car is safely parked and cut the relay supplying power to the dash-cam. Then go into deep sleep.
+
+* If the WiFi is not found, assume the car is parked publicly and close the relay, allowing the dash cam to enter parking mode.
+
+* When the car is turned on, wake the ESP from deep sleep and have it close the relay, thus supplying power to the dash-cam for the drive.
+
+That solution, or at least my implementation of it, can be found in this repository. Along with a few bonus features thrown on top such as:
+
+* Supplying power to an optional GPS tracker.
+
+* Supplying power to a switched 5V output which follows the state of the dash-cam switched output. This is useful if you have a 4G WiFi module or something in the car you want the dash-cam to connect to.
+
+* Ability to send a command to the ESP32 over Bluetooth which will set it to cut power to the dash-cam & 5V output when the car is off regardless of WiFi proximity (useful for if you take the car on holiday etc).

Installation/README.md

@@ -0,0 +1,3 @@
+# Vehicle Installation
+
+TODO: Expand these installation intructions when first prototype is built.

PCB/README.md

@@ -1,16 +1,17 @@
 # PCB
-
 ## Versions
-There are two versions of the PCB in this repository. One which makes use of an external dashcam bettery such as the BlackVue B-130X and one which uses the vehicle battery directly. These are located in their respective subfolders. The project is built with the external battery version in mind as that's what I intend to use, however as it presents an additional financial barrier the PCB for the alternative version exists too.
+There are two versions of the PCB in this repository. One which makes use of an external dash-cam battery such as the BlackVue B-130X and one which uses the vehicle battery directly. These are located in their respective sub-folders.
+
+The project is built with the external battery version in mind as that's what I intend to use, however as it presents an additional financial barrier the PCB for the alternative version exists too.
 
 Please note that, while cheaper and smaller in overall form factor, the no-battery version has the potential to drain your vehicles battery and offers no low-voltage protection on its own.
 
 ## Modifications
-The editable project files for each PCB is included within each subfolder under "Project Files". The PCBs were designed using the Standard Edition of [EasyEDA](https://easyeda.com). Other software exists such as the open source KiCad and the commercial software EAGLE.
+The editable project files for each PCB is included within each sub-folder under "Project Files". The PCBs were designed using the Standard Edition of [EasyEDA](https://easyeda.com). Other software exists such as the open source KiCad and the commercial software EAGLE.
 
 After giving each of these a try, I found EasyEDA had the softest learning curve for both myself and anyone wanting to make modifications, as well as the virtue of offering an in-browser editor thereby making it even more accessible.
 
-Either way, feel free to import and modify using a software of your preferance and (as always) consider contributing back any improvements you may come up with.
+Either way, feel free to import and modify using a software of your preference and (as always) consider contributing back any improvements you may come up with.
 
 ## Ordering
 Included in each of the PCB directories is a Gerber file which may be used to order prints of the PCBs from providers such as JLCPCB and PCBWay. It's a fairly standard format and should be accepted by most PCB printing providers.