add 3d-print docs

docs/3dphardware_dev/breakaway.rst

@@ -0,0 +1,33 @@
+Step 4: Assembling the Breakaway
+==================================
+
+How to assemble the breakaway for the BusKill cable.
+
+Before you start
+------------
+
+Safety Precautions
+^^^^^^^^^^^^^^^^^^^
+- Handle the super glue with care to avoid skin contact.
+- Keep magnets away from electronic devices and magnetic storage media.
+- Use appropriate tools and safety equipment while assembling the parts.
+
+You will need
+^^^^^^^^^^^^^^
+- Prepared pogo wires
+- USB male
+- Superglue
+- Screws
+
+
+Procedure
+----------
+1. **Assemble the Parts**:
+   - Align the 3D printed parts and assemble them together.
+   - Use screws to secure the parts together.
+
+2. **Test the Assembly**:
+   - Verify that the magnetic release mechanism works correctly by connecting and disconnecting the cable.
+   - Ensure that the connection is secure and that the cable releases properly when pulled.
+
+

docs/3dphardware_dev/glossary.rst

@@ -0,0 +1,76 @@
+Glossary
+========
+
+1. `Breakaway End <#Breakaway-End>`_
+2. `BusKill Cable <#BusKill-Cable>`_
+3. `BusKill Software <#BusKill-Software>`_
+4. `Jig <#Jig>`_
+5. `Magnetic Coupler <#Magnetic-Coupler>`_
+6. `Magnetic Release Cord <#Magnetic-Release-Cord>`_
+7. `Pogo Contacts <#Pogo-Contacts>`_
+8. `Pogo Pin <#Pogo-Pin>`_
+9. `Pogo Contact <#Pogo-Contact>`_
+10. `Release End <#Release-End>`_
+11. `USB A <#USB-A>`_
+12. `USB Ejection Event <#USB-Ejection-Event>`_
+13. `USB Insertion Event <#USB-Insertion-Event>`_
+
+Breakaway End
+-------------
+The Magnetic Coupler has two parts. The Breakaway end is the part of the coupler that would separate from the laptop, it terminates the cord that is attached to the user.
+
+BusKill Cable
+-------------
+Used to refer to the assembly of a USB, USB Extender Cord, and Magnetic Coupler with a laptop installed and running BusKill software.
+
+BusKill Software
+----------------
+A program that you can install on Linux, MacOS, or Windows that allows you to set up a trigger that occurs with a USB Ejection Event. The trigger could be locking the screen, shutting down the computer, etc.
+
+Jig
+---
+A printed piece that is used to stabilize something during assembly.
+
+Magnetic Coupler
+----------------
+The Magnetic Coupler has two parts, the Breakaway End and the Release End. These two parts contain magnets and contacts. The coupler is designed so that when the magnets are in place, the Pogo Pins and Pogo Receptors make contact and transfer data and power.
+
+Magnetic Release Cord
+---------------------
+*AKA Magnetic Breakaway Cord*
+
+All of these terms are used to refer to the assembly of a USB A, USB A Extender Cord, and Magnetic Coupler.
+
+Pogo Contact
+------------
+Contacts refer to either the Pogo Pins or the Pogo Receptors. For the Magnetic Coupler to work, the contacts move the data and power from one end of the magnetic coupler to the other so that the USB device functions as expected.
+
+Pogo Pin
+--------
+The Pogo Pin is a spring loaded pogo pin. It is soldered to a pin of a USB A port and housed in the Release End of the Magnetic Coupler. When it is in contact with a Pogo Receptor on the end of a USB Extender Cord, it completes the circuit.
+
+Pogo Receptor
+-------------
+The Pogo Receptor is a conductive contact. It is soldered to the wires of a USB Extender Cord and housed in the Breakaway End of the Magnetic Coupler.
+
+Release End
+-----------
+The Magnetic Coupler has two parts. The Release end is the part of the coupler that would remain connected to the laptop, it terminates the cord that ends with the USB that is inside the computer.
+
+USB A
+-----
+USB A is a type of USB connection. It's the type of connection USB drives use.
+
+USB Ejection Event
+------------------
+What happens when you remove a USB drive from a computer's USB port (or otherwise interrupt the connection, such as with a magnetic coupler) and the computer begins the process of recognizing the disconnection.
+
+USB Extender Cord
+-----------------
+*AKA USB Extension Cable*
+
+The USB Extender Cord is a cord that has a USB female port on one end and a USB male port at the other end. In the BusKill project, this must necessarily be a Data cord, because the project requires a USB data connection.
+
+USB Insertion Event
+-------------------
+What happens when you insert a USB drive into a computer's USB port and the computer begins a process of recognizing the device and establishing a connection.

docs/3dphardware_dev/index.rst

@@ -0,0 +1,44 @@
+.. _3dphardware_dev:
+
+3D-Printed Magnetic Release Developer Guide
+==========================================
+.. image:: /images/3dassembly/buskillassembled.png
+  :width: 400
+  :alt: photograph of assembled 3D printed magnetic release
+
+.. note::
+
+   This project is under active development.
+
+This guide contains assembly instructions for a magnetic breakaway release using a 3D-printed shell for encasing easily sourceable components.
+
+.. toctree::
+   overview
+   printparts
+   preppogos
+   release
+   breakaway
+   magnets
+   testing
+   glossary
+
+
+In the News
+------------
+
+Hill, Ash (May 02, 2023). `"3D Print Your Own USB BusKill Module to Protect Data". <https://www.tomshardware.com/news/3d-printable-buskill-cable>`_ Tom's Hardware.
+
+Halfacree, Gareth (May 08, 2024). `"Melanie Allen Wants to Bring Dead-Man Switches to All with a 3D-Printable BusKill Adapter. <https://www.hackster.io/news/melanie-allen-wants-to-bring-dead-man-switches-to-all-with-a-3d-printable-buskill-adapter-8383a371ee2e>`_ hackster.io
+
+
+More Information
+-----------------
+
+- `What is BusKill? <https://tech.michaelaltfield.net/2020/01/02/buskill-laptop-kill-cord-dead-man-switch>`_
+- `BusKill YouTube <https://www.youtube.com/channel/UC5Njxb027m2OmrocrH33oew>`_
+- `BusKill Crowdsupply <https://www.crowdsupply.com/alt-shift/buskill>`_
+- `BusKill Open Collective <https://opencollective.com/buskill>`_
+- `BusKill Documentation <https://docs.buskill.in>`_
+
+* :ref:`search`
+

docs/3dphardware_dev/magnets.rst

@@ -0,0 +1,27 @@
+Step 5: Adding the magnets
+===========================
+
+We add the magnets last for a few reasons. 
+- Orientation is the easiest thing to mess up. It's good to test your connection before adding the magnets.
+- Other components such as pogo pins and wires and soldering guns attract to magnets and so their presense during earlier parts of the assembly can be frustrating and dangerous.
+
+Before you start
+-----------------
+
+Precautions
+^^^^^^^^^^^^
+- magnet orientation is important
+- careful with the glue bb
+- make sure not to avoid appling heat to the magnets
+
+You will need
+^^^^^^^^^^^^^^
+- magnets
+- superglue
+- wire crimper or pliers
+
+Procedure
+-------
+
+1. Stack the cubes 2x2. 
+2. Use the caliper to pressfit the magnets carefully into place

docs/3dphardware_dev/overview.rst

@@ -0,0 +1,44 @@
+About the 3D-Printed Magnetic Release
+======================================
+
+The 3D printed magnetic release for the BusKill cable consists of two printable parts, the Breakaway and the Release. The Breakaway and the Release are connected between a usb drive, usb cord, and usb port on the computer. Magnets and pogo pins are inserted into the "faces" or "contact points" so that they easily break away, severing the connection between the computer and a usb drive.
+
+The Breakaway is an assembly of a Breakaway printed part, 22 awg wire, pogo receptors, USB port (female), and magnets.
+
+The Release is an assembly of a Release printed part, 22 awg wire, pogo pins, USB male, jig, and  magnets.
+
+Before you start
+-----------------
+
+Precautions
+^^^^^^^^^^^^^^^^^^
+- Handle the super glue with care to avoid skin contact.
+- Keep magnets away from electronic devices and magnetic storage media.
+- Use appropriate tools and safety equipment while assembling the parts.
+
+.. image:: /images/3dassembly/partsdiagram.png
+  :width: 400
+  :alt: parts diagram
+
+You will need
+^^^^^^^^^^^^^^
+  - 3D printed parts - https://github.com/goldfishlaser/usb-a-magnetic-breakaway
+  - Magnets
+  - Pogo Pins
+  - Pogo Contacts
+  - 28 AWG Wire
+  - Super glue
+  - USB male
+  - USB female
+  - Cable
+  - Screws
+  - Solder
+  - Wire stripper
+  - Helping hands
+  - Eraser putty
+  - Screwdriver
+  - Soldering iron
+
+
+
+

docs/3dphardware_dev/preppogos.rst

@@ -0,0 +1,35 @@
+Step 2: Prep the pogo connections
+==================================
+
+We create both pogo connections first to save time as we wait for the glue to dry for both.
+
+Before you start
+-----------------
+
+Precautions
+^^^^^^^^^^^^
+- Make sure to avoid globs of solder
+- Pogos get hot during soldering
+- Use proper ventiliation and PPE
+
+You will need
+^^^^^^^^^^^^^^
+- 22 awg wire
+- Pogo pins
+- Pogo contacts
+- wire jigs
+- superglue
+- soldering iron
+- solder
+
+Steps
+------------
+
+1. Strip 8 x 10mm 22 awg wire 
+2. Solder 4 of the wires to pogo pins
+   .. image:: /images/3dassembly/pogopinwires.jpg
+      :width: 400
+      :alt: photograph of wires soldered to pogo pins
+3. Glue the wires into the jig
+4. Solder 4 of the wires to pogo contacts
+5. Glue the wires onto the jig

docs/3dphardware_dev/printparts.rst

@@ -0,0 +1,23 @@
+Step 1: Print the parts
+===============================
+
+How to print the parts.
+
+Before you start
+-----------------
+
+Precautions
+^^^^^^^^^^^^^^^^^^^
+- Make sure to print with a brim
+
+You will need
+^^^^^^^^^^^^^^
+- 3D printer
+
+Procedure
+----------
+
+1. **Download**:
+   - URL
+2. **Edit in OpenSCAD**:
+   - Instructions

docs/3dphardware_dev/release.rst

@@ -0,0 +1,37 @@
+Step 3: Assembling the Release
+===============================
+
+How to assemble the release for the BusKill cable.
+
+Before you start
+-----------------
+
+Precautions
+^^^^^^^^^^^^^^^^^^^
+- Handle the super glue with care to avoid skin contact.
+- Keep magnets away from electronic devices and magnetic storage media.
+- Use appropriate tools and safety equipment while assembling the parts.
+
+You will need
+^^^^^^^^^^^^^^
+- Prepared pogo wires
+- USB female
+- Superglue
+- Screws
+
+Procedure
+----------
+
+1. **Assemble the Parts**:
+   - Align the 3D printed parts and assemble them together.
+   - Use screws to secure the parts together.
+
+2. **Test the Assembly**:
+   - Verify that the magnetic release mechanism works correctly by connecting and disconnecting the cable.
+   - Ensure that the connection is secure and that the cable releases properly when pulled.
+
+Troubleshooting
+---------------
+- If the parts do not fit together properly, check for any leftover support material or rough edges and sand them down.
+
+

docs/3dphardware_dev/testing.rst

@@ -0,0 +1,17 @@
+Testing and Troubleshooting
+=========================================================
+
+Testing
+------------
+- TBD
+
+Troubleshooting
+---------------
+- If the magnets are not attracting each other, check the polarity and ensure they are correctly oriented.
+- If the parts do not fit together properly, check for any leftover support material or rough edges and sand them down.
+
+Maintenance
+-----------
+- Periodically check the magnetic release mechanism for wear and tear.
+- Replace any damaged parts as necessary.
+

docs/conf.py

@@ -224,8 +224,12 @@
 ############################
 html_context['display_lower_left'] = True
 
-from git import Repo
-repo = Repo( search_parent_directories=True )
+try:
+    from git import Repo
+    repo = Repo( search_parent_directories=True )
+except ImportError as e:
+    print(f"Warning: {e}. GitPython may not be installed or accessible.")
+    repo = None
 
 if 'current_version' in os.environ:
 	# get the current_version env var set by updatePages.sh

docs/hardware_dev/index.rst

@@ -7,8 +7,10 @@ This section will describe how to build the BusKill hardware cable.
 
 For information on how to setup and use the BusKill cable before using the BusKill app, see :ref:`hardware_usr`
 
+For information on how to assemble a 3D-printed magnetic release case, see :ref:`3dphardware_dev` 
+
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
 
    bom
    assembly