Various changes and polish to entries (#81)

docs/diy/assembling.md

@@ -1,29 +1,41 @@
 
 This guide mainly focuses on the parts listed in the [Hardware Buy guide](hardware-buying.md).
 
-## Hardware Requirements
+## Hub Hardware Requirements
 
-+ ESP-32
-+ 433 MHz transmitter
-+ Soldering station (optional)
++ ESP32 board
++ 433 MHz transmitter (ASK/OOK)
++ Soldering station (potentially optional)
 + Hookup wire (optional, depending on whether the pins line up)
 
 ## What/Where to buy?
 
-See the [Hardware Buy guide here](hardware-buying.md). For the board/ESP-32 assembly you need the ESP-32 and a 433 MHz transmitter.
+See the [hardware buying guide here](hardware-buying.md). For the hub assembly you'll need an ESP32 and a 433 MHz transmitter.
 
-## Figuring out the PINs
+## Figuring out the pins
 
-Any digital output pin on your micro-controller should work for outputting the signal for the transmitter, however the default is often close to the positive and ground pins on the controller. See the [boards](../hardware/boards/index.md) section dedicated to the micro-controller you are using to decide which pin to use.
+You will need to connect the 433MHz transmitter's signal input pin to one of the ESP32's IO pins, and you can optionally connect an Emergency Stop button/switch to another pin.
+
+*Most* of the GPIO pins on any given ESP32 board should work for both RF TX and E-Stop, however some pins are reserved for special usage and will return an error if you attempt to use them during setup. If you run into that error, adjust your setup to use a different pin with a higher number.
+
+Note down which GPIO pins you soldered to, as you will need to enter them during setup in a later step.
 
 For example, if you bought a [Wemos Lolin S3](../hardware/boards/wemos/lolin-s3.md) and a [Open Smart Transmitter](../hardware/transmitter/china/open-smart.md), simply connect the 5V to the 5V pins (aka VCC), ground to ground, and any numbered pin to data, for example, the 12 pin.
 
-!!! warning "Pins"  
-    You will need to set your RFTX pin during setup. If the pin is incorrect the transmitter wont be able to send any signals.  
-    If you already went through the setup process, you can change the pin via a serial terminal with the command `rftxpin #` where `#` is your pin number.  
-    Or you reenable the Captive Portal on the website and connect to it again with your phone.
+!!! warning "Don't forget to enter these during setup!"
+    You will need to set your RF TX pin during setup. If the pin is incorrect the transmitter wont be able to send any signals to the shockers.
+
+    If you already went through the setup process, you can change the pin via a serial terminal with the command `rftxpin #` where `#` is your pin number.
+
+    You can change E-Stop pin with `estop pin #` where `#` is your pin number.
+
+    Or, you can re-enable the Captive Portal on the website under the Hub's "..." menu and connect to it again with your phone.
+
 
 ![Example Pinout](../static/diy/pinout.png)
 
+!!! warning "Logic level compatibility"
+    Please note that all ESP32s operate at 3.3V logic levels. To avoid overvolting your ESP's IO pins, it is recommended to either: connect your transmitter's power input to a 3V supply pin on the ESP's board, or use a logic-level shifter if your transmitter ***really* requires** more than 3V power to operate.
+
 
-**Next step is [flashing the firmware.](../guides/openshock-how-to-flash-your-board.md)**
+**Next step is [flashing the firmware!](../guides/openshock-how-to-flash-your-board.md)**

docs/diy/hardware-buying.md

@@ -14,11 +14,11 @@ These are the **recommendations** of the OpenShock maintainers. This list is **n
 
 ### ESP32-S3
 
-We recommend the `ESP32-S3` chip, specifically the `N16R8` variant for its 16 MiB of flash. The [Wemos Lolin S3](../hardware/boards/wemos/lolin-s3.md) board satisfies all these criteria.  
+We recommend the `ESP32-S3` chip, specifically the `N16R8` variant for its 16 MiB of flash. The [Wemos Lolin S3](../hardware/boards/wemos/lolin-s3.md) board satisfies all these criteria.
 
 Requirements for the ESP are:
-- Needs to be a **ESP32** specifically. Not a 8266 or other!
-- 4MB or more of flash
+- Needs to be a **ESP32** specifically, including -S and -C variants! ESP8266 is **NOT** supported!
+- Minimum flash size: 4MB
 
 ## 433 MHz Transmitter
 

docs/diy/index.md

@@ -1,2 +1,11 @@
 # Do-It-Yourself
 
+### As a user
+
+[Buying parts for my own hub](./hardware-buying.md)
+
+[Assembling my hub](./assembling.md)
+
+### As a host
+
+[Setting up my own OpenShock instance](../guides/selfhosting/index.md)

docs/guides/openshock-first-setup.md

@@ -1,12 +1,12 @@
 # First time setup
 
 !!! danger "Safety Warning"
-    **Don't wear the shocker somewhere near your neck or your heart.**  
+    **Don't wear the shocker somewhere near your neck or your heart.**
     Check out [Safety](../home/safety-rules.md) for more information.
 
-!!! danger "Safety Warning" 
-    **Do not touch the pins of the shocker with both hands at the same time.** 
-    The electricity could flow through your heart. 
+!!! danger "Safety Warning"
+    **Do not touch the pins of the shocker with both hands at the same time.**
+    The electricity could flow through your heart.
 
 ## What you need
 
@@ -20,9 +20,9 @@
 
 ## Setup the OpenShock hub
 
-1. Connect your **Phone** to the hub:
+1. Wirelessly connect your **Phone** to the hub:
     1. Plug your hub in and ensure it has power.
-    2. On your phone, search for a Wi-Fi network named similar to ``OpenShock-XX:XX:XX:XX:XX:XX`` and connect to it. 
+    2. On your phone, search for a Wi-Fi network named similar to ``OpenShock-XX:XX:XX:XX:XX:XX`` and connect to it.
     ??? Info "Images (click to expand)"
         ![Image "image"](../static/guides/first-setup/WiFioverview.png)
 2. Connect to the hub via the network:
@@ -35,10 +35,10 @@
 
 3. Set the RF TX Pin if needed
 
-!!! warning "RF TX Pin" 
-    **DO NOT** change the RF TX Pin **UNLESS IT IS NOT AUTOMATICALLY DETECTED** or you are using a DIY hub.
-    This is an advanced feature. It should be set correctly by default after flashing the OpenShock firmware.  
-    If the pin is not automatically selected, you can open a Serial terminal and send the command `rftxpin #` where `#` is your pin number.  
+!!! warning "RF TX Pin"
+    **DO NOT** change the RF TX Pin **UNLESS IT IS NOT AUTOMATICALLY DETECTED** *or* you are using a DIY hub.
+    This is an advanced feature. It should be set correctly by default after flashing the OpenShock firmware if you are using a known board.
+    If the pin is not automatically selected, you can open a Serial terminal and send the command `rftxpin #` where `#` is your pin number.
     If you do not know how to do this, you can also re-enable the captive portal (hotspot of the Hub) to re-configure it. For more information see the page dedicated to your micro-controller under [boards](../hardware/boards/index.md).
 
 1. Create a hub on the website:
@@ -63,7 +63,7 @@
             ![Image "image"](../static/guides/first-setup/findpaircode.png)
             ![Image "image"](../static/guides/first-setup/paircodeexample.png)
 3. The hub is now connected!
-    - If everything went well, it should show a **green icon** next to the device name on the website.  
+    - If everything went well, it should show a **green icon** next to the device name on the website.
     ![Image "image"](../static/guides/first-setup/checkifonline.png)
 
 ## Pairing shockers
@@ -89,7 +89,7 @@
     4. You must click the icon before the shocker's pairing mode times out (while the shocker's LED is flashing quickly).
     ??? Info "Images (click to expand)"
         ![image](../static/guides/first-setup/find_sound_button.png)
-**Everything should work now, have fun!** 🎉  
+**Everything should work now, have fun!** 🎉
 
 !!! question "Need Help?"
     If you need additional help, join our [Discord](https://discord.gg/OpenShock)

docs/guides/openshock-how-to-flash-your-board.md

@@ -10,20 +10,20 @@
     Ensure you have a cable that supports data transfer, and neither the port nor cable is damaged.
 
 !!! Info
-    If you received your hub from an OpenShock hardware vendor, you can likely skip this step! Any updates can be [performed wirelessly](../guides/openshock-how-to-update.md) after the initial setup.
+    If you received your hub from an OpenShock hardware vendor, you can likely **skip this step**! Any updates can be [performed wirelessly](../guides/openshock-how-to-update.md) after the initial setup.
 
 ## Flashing the firmware
 1. Plug your hub into your PC using a USB cable.
 2. Open the [Flashtool](https://next.openshock.app/flashtool).
-3. Click "Select Device" and select your hub in the Popup window.  
+3. Click "Select Device" and select your hub in the Popup window.
 If your hub is not showing up click on "Install Drivers", after that repeat this step.
 ![Connect Controller](../static/guides/how-to-flash/Connect_Device_Flashtoolguide.png)
 4. Ensure you have the "Stable" channel selected.
-5. Ensure the correct board is selected.
-![Settings](../static/guides/how-to-flash/settings.png)  
-6. Press Flash and let it do it's thing, keep the window open and it will tell you when it's done.  
-7. When everything went well you board will restart and you should be able to run through the [First Setup](../guides/openshock-first-setup.md) steps to configure your hub and link it to your shocker etc.  
-8. (Optional) If you have issues after flashing it try again with "Erase everything before flashing" enabled.  
+5. Ensure the correct [board](../hardware/boards/index.md) is selected.
+![Settings](../static/guides/how-to-flash/settings.png)
+6. Press Flash and let it do it's thing, keep the window open and it will tell you when it's done.
+7. When everything went well you board will restart and you should be able to run through the [First Setup](../guides/openshock-first-setup.md) steps to configure your hub and link it to your shocker etc.
+8. (Optional) If you have issues after flashing, try again with "Erase everything before flashing" enabled.
 
 ### Troubleshooting
 
@@ -39,16 +39,30 @@ If you experience issues with connecting the flash tool to your esp, there is a
 
 Try a couple of different USB cables, USB ports on your computer and if available on a different machine entirely.
 
-#### Pull IO0 to GND
+#### Manually start bootloader
 
-You can put most esp32's into download mode by temporarily connecting GPIO 0 to a Ground Pin when the esp is booting.
+Depending on the driver or board, your computer may fail putting the ESP32 into a flashable state.
 
-Example PIN's for the Wemos D1 Mini
+Most boards will have a pair of buttons. The first button labelled "Boot", "IO0", or even just "B". The second labelled "Reset", "RST", or "EN".
+
+First, attempt flashing **while holding down "Boot"**.
+
+If that doesn't work, try holding down "Boot" and then tapping "Reset". That will reboot the ESP32, and also enter the bootloader, making it ready to recieve new firmware!
+
+Sometimes, you may need to both enter the bootloader manually *and* hold down "Boot" while starting the flashing process.
+
+If you don't have a button, you can still usually short GPIO `0` to Ground while booting to enter the bootloader (for *most* ESP32s).
+
+### Extra tip for ESP32-S and -C boards!
+
+On some boards without firmware, you won't see a Serial port until you enter the Bootloader manually using the two-button steps above!
+
+Example pins for the Wemos D1 Mini
 
 ![Wemos D1 Mini GND Figure](../static/boards/wemos-d1-mini-esp32/gnd-figure.webp)
 ![Wemos D1 Mini GND Figure 2](../static/boards/wemos-d1-mini-esp32/gnd-figure2.webp)
 
-#### Manually flash using EspTool.py
+#### Manually flash using `esptool.py`
 
 1. [Download esptool](https://github.com/espressif/esptool/releases/latest) (for windows the file is called something like `esptool-vx.x.x-win64.zip `)
 2. [Download firmware .bin](https://github.com/OpenShock/Firmware/releases/latest) for your board
@@ -58,5 +72,14 @@ Example PIN's for the Wemos D1 Mini
 6. Execute the command `esptool write_flash 0x0 OpenShock_xxx-name-xxx.bin`. Replace firmware name with your actual file name.
 7. Wait for it to complete flashing and you should be ready to go :partying_face:
 
+#### Manually flash using `espflash` (alternative to `esptool.py`)
+1. Download via [GitHub here](https://github.com/esp-rs/espflash/releases) (or if you have Rust's [cargo](https://doc.rust-lang.org/cargo/) installed, you can run `cargo install espflash`).
+2. [Download firmware .bin](https://github.com/OpenShock/Firmware/releases/latest) for your board
+3. Extract espflash
+4. Move the downloaded firmware `.bin` file into the folder with `espflash.exe`
+5. Open a command line (`cmd` or `powershell`) in that folder
+6. Execute the command `espflash write-bin 0x0 OpenShock_xxx-name-xxx.bin`. Replace firmware name with your actual file name.
+7. Wait for it to complete flashing and you should be ready to go :partying_face:
+
 !!! failure "Still not working?"
     Try again, if you still got problems after following this guide join our [discord](https://discord.gg/OpenShock) and we will see how we can help you!

docs/hardware/transmitter/index.md

@@ -7,7 +7,13 @@ tags:
 
 # Transmitter
 
-Any 433 MHz transmitter that is compatible with ASK / OOK should work with OpenShock. Below are transmitters that have been tested to work.
+Any 433 MHz transmitter that is compatible with ASK / OOK should work with OpenShock.
+
+!!! warning "Logic level compatibility"
+    Please note that all ESP32s operate at 3.3V logic levels. To avoid overvolting your ESP's IO pins, it is recommended to either: connect your transmitter's power input to a 3V supply pin on the ESP's board, or use a logic-level shifter if your transmitter ***really* requires** more than 3V power to operate.
+
+
+Below are transmitters that have been tested to work.
 
 !!! warning "Ask for transmitters"
     This vendor sells the transmitter and receiver **as a pair**. If you would like 2 transmitters instead. Ask the seller for **only transmitters**.

docs/quickstart/what-you-need.md

@@ -22,4 +22,4 @@ A hub connects OpenShock to the shock device via a micro-controller and a 433 MH
 
 ### 3. Shockers
 
-See the [Shockers](../hardware/shockers/index.md). We recommend the [CaiXianlin](../hardware/shockers/caixianlin.md) shockers.
+See [Shockers](../hardware/shockers/index.md). We recommend the [CaiXianlin](../hardware/shockers/caixianlin.md) shockers.

docs/troubleshooting/hub.md

@@ -5,19 +5,19 @@
 This could be due to 3 main reasons:
 
 - The Hub is offline
-- The RFTX pin is not configured correctly
+- The RF TX pin is not configured correctly
 - The transmitter is not connected properly
 
 ### Hub is offline
 
 Make sure the Hub is online on the Website, you can confirm this by checking if the dot next to the name of it is green.
 
-### RFTX pin is not configured correctly
+### RF TX pin is not configured correctly
 
 !!! warning
     If you bought a pre built Hub this is unlikely, but might be the case, especially after a re-flash.
 
-The RFTX pin is the GPIO pin on your ESP32 that controls the signal to the antenna.
+The RF TX pin is the GPIO pin on your ESP32 that controls the signal to the antenna.
 Therefor you want to configure the pin number to be matching what is wired up to the signal of your transmitter.
 
 Usually you set this pin during the first time setup of your hub. If you have already done this setup and your hub is online, there is two ways to change the pin after that.
@@ -27,9 +27,9 @@ Usually you set this pin during the first time setup of your hub. If you have al
 
 ### Transmitter is not connected properly
 
-Make sure your GND and VCC are properly connected. VCC is either 5V or 3.3V, depending on what antenna you use and how much you want your range to be.  
+Make sure your GND and VCC are properly connected. It's recommended to use 3V supply for the transmitter's VCC (voltage input), using 5V may result in inoperation or damage to your hardware if proper precautions arent taken in the form of logic-level shifters.
 
-Also make sure you signal is connected to a GPIO pin that is free to use. For example in the lolin s3 we can use pin 12, which conveniently also is GPIO 12.
-Do note that the numbers on the PCB do not always match the actual GPIO pin number. Refer to the datasheet of your board for more information.
+Also make sure you signal is connected to a GPIO pin that isn't blacklisted. When setting a pin in the setup portal or via the serial console, the firmware will warn you if you try to use an invalid pin.
+Do note that the numbers on the PCB may not always match the actual GPIO pin number! Refer to the datasheet of your board to ensure you're connecting to the correct GPIO pin number.
 
-Also make sure you are using a Transmitter! Not the Receiver!
+Additionally, make sure you are using a Transmitter module! The Receiver modules are not used at this time!

docs/vendors/hardware/foghunter.md

@@ -13,8 +13,6 @@ Started `2024-11-23`.
 
 Current controller on sale: [Wemos D1 mini](../../hardware/boards/wemos/d1-mini-esp32.md).
 
-[Github](https://github.com/nullstalgia)
-
 ## Contact
 
 - :simple-discord: Discord -- `foghunter`