Merge pull request #24 from Kyobinoyo/kyo-guides

fixes and formatting
OpenShock · Nov 21, 2023 · dab0eb6 · dab0eb6
2 parents 63ea9a9 + 384fade
commit dab0eb6
Show file tree

Hide file tree

Showing 5 changed files with 165 additions and 136 deletions.
diff --git a/docs/guides/openshock-first-setup.md b/docs/guides/openshock-first-setup.md
@@ -7,8 +7,8 @@
 ## What you need
 - USB cable with at least one USB-C connector and a PC _**or**_ USB Power adapter
 - A Smartphone with a Webbrower (Chrome, Firefox etc.)
-- ESP board
-- Shocker
+- [ESP board](../hardware/boards/index.md)
+- [Shocker](../hardware/shockers/index.md)
 - [Shocklink account](https://shocklink.net/)
 
 
@@ -21,7 +21,9 @@
 3. Now open your **phones browser** and type in ``10.10.10.10`` or ``openshock.local`` this should open up a web-interface for the ESP that looks like this:  
 ![Image "image"](../static/guides/first-setup/ESPWebGUI.png)  
 4. Lookup your Wi-Fi Network in the web-interface, press the green button next to it and type in your Wi-Fi password then press submit.
-5. Set the RF TX Pin, that is the number of the IO pin that the RF antenna data is connected to. (default 12, for pishock boards that is 15, if you don't know your pin, try asking for help on our [Discord](https://shocklink.net/discord)), type in your pin and press **Set** to change it.
+5. Set the ``RF TX Pin``, that is the number of the IO pin that the RF antenna data is connected to.  
+(default 12, if you don't know your pin, check out the [board documentation #pinout](../hardware/boards/pishock/2023-pishock.md/#pinout) and see if your board is documented or try asking for help on our [Discord](https://shocklink.net/discord)).  
+Type in your pin and press **Set** to change it.
 6. **On your PC** open [Shocklink.net](https://shocklink.net/) and create an account, if you don't have one already, after that go to ``Devices`` and click the **green + icon** at the lower right corner to create a new device.   
 ![Image "image"](../static/guides/first-setup/findaddbutton3.png)  
 7. Give it a name. To do that click on the **three dots** next to your newly created device's name and select **edit**, type in the name for the ESP (your name for example) into the name field, then press save.  

diff --git a/docs/guides/shocklink-sharelinks.md b/docs/guides/shocklink-sharelinks.md
@@ -32,7 +32,7 @@ Your new share link should popup as a new entry on the page.
   5. On the right side are three dots that open the ``context menu`` of the link.    
 ![Image "Image"](../static/guides/how-to-sharelinks/addshockertosharelink.png)  
 
-  6. Click on ``Add shocker`` and choose your shocker, you can add multiple shockers to the same link, just repeat this step.  
+  6. Click on ``Add shocker`` and choose your shocker, you can add multiple shockers to the same link, just repeat step 5 and 6.  
 ![Image "Image"](../static/guides/how-to-sharelinks/addshockertosharelink2.png)  
 
   7.  After adding your shocker(s) to the link you will see the shockers controls, that's it.  
@@ -59,10 +59,10 @@ Your new share link should popup as a new entry on the page.
   4. To exit the Edit Mode open the share links context menu again and choose ``Edit Mode``, it will return the controls to their normal color indicating that the Edit Mode is not active anymore.  
 
 ### Pause your Share link
-  1. To ``Pause`` your share link go to Share links open the link you want to pause and click on the little pause icon next to the share links name.  
+  1. To ``Pause`` your share link go to Share links, open the link you want to pause and click on the little pause icon next to the share links name.  
 ![Image "Image"](../static/guides/how-to-sharelinks/pauseshocker.png)  
 
-  2. It should now ``blur`` the shocker controls telling you it's paused, as long as the link is paused it will not accept any commands.
+  2. It should now ``blur`` the shocker controls telling you it's paused, as long as the link is paused your shocker will not accept any commands from **this** link.
 ![Image "Image"](../static/guides/how-to-sharelinks/pausedlink.png)  
 
   3. To un-pause the share link again simply click on the ``Play Icon``.

diff --git a/docs/guides/shockosc-avatar-setup.md b/docs/guides/shockosc-avatar-setup.md
@@ -51,45 +51,44 @@
 
 ## List of available parameters
 
-### Avatar Dynamic Parameters  
-
-??? Info "``ShockOsc/{ShockerName}`` (bool)"
-    when set to ``true`` and held, will trigger a normal shock in ShockOSC
-
-
-??? "``ShockOsc/{ShockerName}_Stretch`` (float)"  
-    can be used to control the shock intensity  
-    (ex. stretch a bone to 50% and let go to get shocked for 50% intensity)  
-
-??? Info "``ShockOsc/{ShockerName}_IsGrabbed`` (bool)"   
-    mainly used  to indicate that a Physbone is grabbed
-
-??? "``ShockOsc/{ShockerName}_IShock``  (bool)" 
-    if set to ``true`` will shock immediately ignoring the configurated ``HoldTime``.  
-
-### Visual Parameters
-??? Info "``ShockOsc/{ShockerName}_Active`` (bool)"
-    can be used to display an active shock on your avatar (when the shocker is active, ShockOSC will set this to ``true`` if not it will be ``false``)
-
-??? "``ShockOsc/{ShockerName}_Cooldown`` (bool)"
-    can be used to read out if the shocker is on cooldown  
-
-??? Info "``ShockOsc/{ShockerName}_CooldownPercentage`` (float)"
-    Reads out the shocker cooldown, 1 means cooldown and 0 means no cooldown.  
-    can be used to make a loading bar for example.  
-
-??? "``ShockOsc/{ShockerName}_Intensity``  (float)"
-    represents how close the shock was to maximum intensity from ``IntensityRange``
-
-### Dummy Shockers  
-??? Info "``_All``"
-    can be used in place of a shocker name, **represents all** shockers configured in the ShockOSC config.  
-    (ex: if **ShockOsc/_All** is set to ``true`` on you Avatar, every shocker configured in ShockOSC will be triggered at the same time)
-
-??? "``_Any``"
-    can be used in place of a shocker name, **represents any** shocker configured in the ShockOSC config.  
-    (ex: if at least one of your shockers are currently shocking **ShockOsc/_Any_Active** will be ``true``)  
-
-### Config Parameters  
-??? Info "``ShockOsc/_Config/Paused`` (bool)"
-    As long as this parameter is ``true``, all activity by ShockOsc will be paused, shockers will still receive commands via [Share links](shocklink-sharelinks.md) and Share codes.  
+=== "Avatar Dynamic Parameters "
+    ???+ Info "``ShockOsc/{ShockerName}`` (bool)"
+        when set to ``true`` and held, will trigger a normal shock in ShockOSC
+
+
+    ???+ "``ShockOsc/{ShockerName}_Stretch`` (float)"  
+        can be used to control the shock intensity  
+        (ex. stretch a bone to 50% and let go to get shocked for 50% intensity)  
+
+    ???+ Info "``ShockOsc/{ShockerName}_IsGrabbed`` (bool)"   
+        mainly used  to indicate that a Physbone is grabbed
+
+    ???+ "``ShockOsc/{ShockerName}_IShock``  (bool)" 
+        if set to ``true`` will shock immediately ignoring the configurated ``HoldTime``.  
+
+=== "Visual Parameters"
+    ???+ Info "``ShockOsc/{ShockerName}_Active`` (bool)"
+        can be used to display an active shock on your avatar (when the shocker is active, ShockOSC will set this to ``true`` if not it will be ``false``)
+
+    ???+ "``ShockOsc/{ShockerName}_Cooldown`` (bool)"
+        can be used to read out if the shocker is on cooldown  
+
+    ???+ Info "``ShockOsc/{ShockerName}_CooldownPercentage`` (float)"
+        Reads out the shocker cooldown, 1 means cooldown and 0 means no cooldown.  
+        can be used to make a loading bar for example.  
+        
+    ???+ "``ShockOsc/{ShockerName}_Intensity``  (float)"
+        represents how close the shock was to maximum intensity from ``IntensityRange``
+
+=== "Dummy Shockers"  
+    ???+ Info "``_All``"
+        can be used in place of a shocker name, **represents all** shockers configured in the ShockOSC config.  
+        (ex: if **ShockOsc/_All** is set to ``true`` on you Avatar, every shocker configured in ShockOSC will be triggered at the same time)
+
+    ???+ "``_Any``"
+        can be used in place of a shocker name, **represents any** shocker configured in the ShockOSC config.  
+        (ex: if at least one of your shockers are currently shocking **ShockOsc/_Any_Active** will be ``true``)  
+
+=== "Config Parameters"  
+    ???+ Info "``ShockOsc/_Config/Paused`` (bool)"
+        As long as this parameter is ``true``, all activity by ShockOsc will be paused, shockers will still receive commands via [Share links](shocklink-sharelinks.md) and Share codes.  
diff --git a/docs/guides/shockosc-basic.md b/docs/guides/shockosc-basic.md
@@ -20,10 +20,8 @@
 1. [Download](https://github.com/OpenShock/ShockOsc/releases) and store the ``ShockOsc.exe`` file at your desired location on your PC.  
    (at the moment there are two ShockOsc.exe files to download, you only need the ``OpenShock.ShockOsc.exe``)  
 2. Start the .exe for the first time, this will generate a ``config.json`` file in the same location as the .exe, press any button to close the window again.
-3. Open ``config.json`` in a text editor, we need to configure two things , your ``API Token`` and your ``Shocker ID``.  
-Both can be found in your account on [Shocklink.net](https://shocklink.net/)
-
-??? note "Configure the API Token"
+3. Open ``config.json`` in a text editor, we need to configure two things for ShockOsc to work, your ``API Token`` and your ``Shocker ID``.    
+??? abstract "Configure the API Token"
     1. On [Shocklink.net](https://shocklink.net/) go to ``API Tokens``  
     ![Image "Image"](../static/guides/shockosc/finds_apitokens.png)  
     2. Press the ``green plus`` at the bottom.  
@@ -40,103 +38,130 @@ Both can be found in your account on [Shocklink.net](https://shocklink.net/)
         Obviously you should use your own APi Token 😉
 
 
-??? note "Configure the Shocker ID"
+??? abstract "Configure the Shocker ID"
     1. On [Shocklink.net](https://shocklink.net/) go to ``Shockers``  
     ![Image "Image"](../static/guides/shockosc/find_shockers.png)  
     2. Open the context menu of the shocker you want to use  
     ![Image "Image"](../static/guides/shockosc/find_shockerid.png)  
     3. Click on edit, and copy the ID  
     ![Image "Image"](../static/guides/shockosc/find_shockerid2.png)  
-    4. In your config you have to create a list for your shockers, there you have to paste your Shocker ID then save your config file.    
-    It should look something like this at the end:  
+    4. In your config you have to create a list for your shockers, there you have to paste your Shocker ID, then save your config file.    
+    It should look like this at the end:  
     !!! example 
-        ```json
-        ...
-        "Shockers": {
-          "SHOCKERNAME": "18b1d0e6a-f9a0-4e93-9812-241eae9271791"}
-        ...
-        ```  
-        ``SHOCKERNAME`` can be replaced by your own name for your shocker, ``leg`` for example, the name doesn't need to match the name on Shocklink.net, this name is later used to create a parameter on your avatar.  
-
-        (optional) You <u><b>can</b></u> also add more shockers, make sure you don't use the same ID or Name twice, this doesn't work.<br>
-        ```json
-        ...
-        "Shockers": {
-          "leftleg": "18b1d0e6a-f9a0-4e93-9812-241eae9271791", 
-          "rightleg": "28b1d0e6a-f9a0-4e93-9812-241eae9271792",
-          "lefttoe": "38b1d0e6a-f9a0-4e93-9812-241eae9271793"}
-        ...
-        ```
+
+        === "One Shocker"
+
+              ```json
+              "Shockers": {
+                "SHOCKERNAME": "18b1d0e6a-f9a0-4e93-9812-241eae9271791"
+                }
+              ```
+        === "Multiple Shockers"
+
+              ```json
+              "Shockers": {
+                "leftleg": "18b1d0e6a-f9a0-4e93-9812-241eae9271791", 
+                "rightleg": "28b1d0e6a-f9a0-4e93-9812-241eae9271792",
+                "lefttoe": "38b1d0e6a-f9a0-4e93-9812-241eae9271793"
+                }
+              ```
+        **SHOCKERNAME** needs to be replaced by your own shocker name, the name is only used for ShockOsc and doesn't need to be the same as the one on the website.
+
+After finishing these steps, save your ``config.json``.   
+ShockOsc is now working and should connect to to your shocker(s) when you start it. 🎉 
+
+!!! success "VRChat Avatar Setup"
+    Check out the [VRChat Avatar Setup](shockosc-avatar-setup.md) Guide!  
+    **Keep reading this guide to configure the limits of your ShockOsc.**
 
 <br></br>
 
 ## Configure Limits
 You can also set limits in ShockOsc. 
+
 !!! Tip
     Time is set in milliseconds  
-    1 second = 1000 milliseconds  
-
-### Random intensity and duration
-This way you will be shocked for a random intensity or random duration or both when someone triggers your ShockOsc.  
-
-1. Open your ``config.json``.
-2. Make sure ``RandomIntensity`` and/or ``RandomDuration`` is set to ``true``, you can configure these individually. 
-3. Edit the ``IntensityRange`` and ``DurationRange``.
-4. Save the config file, you are done! 🎉
-???+ example
-    ```json
-    "Behaviour": {
-      "RandomIntensity": true,    <---- configure this
-      "RandomDuration": true,     <---- configure this
-      "RandomDurationStep": 1000,
-      "DurationRange": {
-        "Min": 1000,              <---- configure this
-        "Max": 10000              <---- configure this
-      },
-      "IntensityRange": {
-        "Min": 1,                 <---- configure this
-        "Max": 100                <---- configure this
-      },
-      "FixedIntensity": 50,
-      "FixedDuration": 2000,
-      "HoldTime": 250,
-      "CooldownTime": 10000,
-      "WhileBoneHeld": "Vibrate",
-      "DisableWhileAfk": true,
-      "ForceUnmute": false
-    },
-    ```
-
-
-### Fixed intensity and duration
-This way you will be shocked for a fixed intensity or duration or both when someone triggers you ShockOsc.  
+    1 second = 1000 milliseconds 
+
+### Shock Modes
+!!! question "Shock Modes?"
+    Yes! You can be shocked for a random intensity/duration or a fixed one.
+
+=== "Random intensity/duration" 
+    Get shocked for a random intensity/duration.  
+
+    1. Open your ``config.json``.
+    2. Make sure ``RandomIntensity`` and/or ``RandomDuration`` is set to ``true``, you can configure these individually. 
+    3. Edit the ``IntensityRange`` and/or ``DurationRange``.
+    4. Save the config file, you are done! 🎉  
+    ???+ example
+        ```json hl_lines="2 3 6 7 10 11"
+        "Behaviour": {
+          "RandomIntensity": true,
+          "RandomDuration": true,
+          "RandomDurationStep": 1000,
+          "DurationRange": {
+            "Min": 1000,
+            "Max": 10000
+          },
+          "IntensityRange": {
+            "Min": 1,
+            "Max": 100
+          },
+          "FixedIntensity": 50,
+          "FixedDuration": 2000,
+          "HoldTime": 250,
+          "CooldownTime": 10000,
+          "WhileBoneHeld": "Vibrate",
+          "DisableWhileAfk": true,
+          "ForceUnmute": false
+        },
+        ```
+=== "Fixed intensity/duration"
+    Get shocked for a fixed intensity/duration.  
+
+    1. Open your ``config.json``.
+    2. Set ``RandomIntensity`` and/or ``RandomDuration``  to ``false``, you can configure these individually. 
+    3. Edit the ``FixedIntensity`` and/or ``FixedDuration`` to the fixed value you want.
+    4. Save the config file, you are done! 🎉  
+    ???+ example
+        ```json hl_lines="2 3 13 14"
+        "Behaviour": {
+          "RandomIntensity": false,
+          "RandomDuration": false,
+          "RandomDurationStep": 1000,
+          "DurationRange": {
+            "Min": 1000,
+            "Max": 10000
+          },
+          "IntensityRange": {
+            "Min": 1,
+            "Max": 100
+          },
+          "FixedIntensity": 50,      
+          "FixedDuration": 2000,    
+          "HoldTime": 250,
+          "CooldownTime": 10000,
+          "WhileBoneHeld": "Vibrate",
+          "DisableWhileAfk": true,
+          "ForceUnmute": false
+        },
+        ```
 
-1. Open your ``config.json``.
-2. Set ``RandomIntensity`` and/or ``RandomDuration``  to ``false``, you can configure these individually. 
-3. Edit the ``FixedIntensity`` and/or ``FixedDuration`` to the fixed value you want.
-4. Save the config file, you are done! 🎉  
-???+ example
-    ```json
-    "Behaviour": {
-      "RandomIntensity": false,    <---- configure this
-      "RandomDuration": false,     <---- configure this
-      "RandomDurationStep": 1000,
-      "DurationRange": {
-        "Min": 1000,
-        "Max": 10000
-      },
-      "IntensityRange": {
-        "Min": 1,
-        "Max": 100
-      },
-      "FixedIntensity": 50,       <---- configure this
-      "FixedDuration": 2000,      <---- configure this
-      "HoldTime": 250,
-      "CooldownTime": 10000,
-      "WhileBoneHeld": "Vibrate",
-      "DisableWhileAfk": true,
-      "ForceUnmute": false
-    },
+### Cooldown
+!!! question "What does a cooldown do?"
+    The cooldown will stop ShockOsc from shocking you for a certain amount of time after the last shock. 
+
+- To configure your cooldown duration, set the ``"CooldownTime":`` inside the ``config.json`` to the value you want.
+!!! example
+    ```json hl_lines="4"
+    "FixedIntensity": 50,
+    "FixedDuration": 2000,
+    "HoldTime": 250,
+    "CooldownTime": 5000,
+    "WhileBoneHeld": "Vibrate",
+    "DisableWhileAfk": true,
+    "ForceUnmute": false
     ```
 
 <br></br>
@@ -184,6 +209,5 @@ After following this guide your config should look something like this:
     }
     ```
 
-
-!!! Tip "Advanced Configuration"
+!!! info "Advanced Configuration"
     On the [ShockOSC repository](https://github.com/OpenShock/ShockOsc) you can see additional configuration examples, but that would go beyond the limits of this simple guide  
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -70,6 +70,8 @@ theme:
     - navigation.instant
     - navigation.tracking
     - navigation.indexes
+    - content.tabs.link
+    - content.code.annotate
   custom_dir: overrides
   palette: 
     # Palette toggle for dark mode
@@ -89,6 +91,8 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
   - tables
   - attr_list
   - pymdownx.emoji: