Merge branch 'main' of https://github.com/sparkfun/SparkFun_Portabili…

…ty_Shield

README.md

@@ -5,6 +5,12 @@ SparkFun Portability Shield
 
 [*SparkFun Portability Shield (DEV-27510)*](https://www.sparkfun.com/products/27510)
 
+The SparkFun Portability Shield adds all the user interface bits needed to take a SparkFun development board into the field. A LiPo battery connector, charger, fuel gauge, and an on/off switch address your power needs. A friction-fit microSD connector allows for data logging. The 1.3in. OLED and a five-way navigation switch provide an excellent user interface. Locking 0.1in. headers along the shield's edge make it easier to solder male pins in place.
+
+I<sup>2</sup>C is used to interface with the display, fuel gauge, and five-way navigation switch (GPIO expander PCA9554). SPI is used to communicate with the microSD card. The power switch uses an ideal diode (LM66200) to disconnect the battery from the system for a sleep current of approximately 4μA.
+
+The Portability Shield has been designed to be usable with any compatible main board, with the [RTK Postcard](https://www.sparkfun.com/products/26916) being the first!
+
 Head to the [Sparkfun Portability Shield Product Manual](http://docs.sparkfun.com/SparkFun_Portability_Shield/) for technical documentation.
 
 

docs/arduino_example.md

@@ -2,4 +2,86 @@
 icon: simple/arduino
 ---
 
+###Example 1: Navigation Switch
 
+This example demonstrates how to use the navigation switch and detect if the SD card is inserted. The !INT pin of the GPIO expander IC (PCA9554) triggers an interrupt any time a button is pressed or an SD card is inserted/removed.
+
+The code for this example can be found in the [Firmware](../Firmware/Example1_NavigationSwitch/) folder of this repository. Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch: 
+
+
+
+One thing to note is that you will also need to install the SparkFun I2C Expander Arduino Library if you haven't already. You can click the link from within the code or you can download the zip from [the GitHub Repository](https://github.com/sparkfun/SparkFun_I2C_Expander_Arduino_Library/archive/refs/heads/main.zip)
+
+<figure markdown>
+[![SparkFun I2C Expander Arduino Library Install](assets/img/I2CExpanderLibraryInstall.png){ width="90%" }](assets/img/I2CExpanderLibraryInstall.png "Click to enlarge")
+<figcaption markdown>SparkFun I2C Expander Arduino Library Install</figcaption>
+</figure>
+
+
+Make sure you've selected the correct board (in this case, we are using the RTK Postcard) and port in the Tools menu and then hit the upload button. Once the code has finished uploading, go ahead and open a [Serial Monitor](https://learn.sparkfun.com/tutorials/terminal-basics). You should see something similar to the following. 
+
+<figure markdown>
+[![Arduino Example 1 Output](assets/img/Example1_Output.jpg){ width="90%" }](assets/img/Example1_Output.jpg "Click to enlarge")
+<figcaption markdown>Example 1 Output</figcaption>
+</figure>
+
+
+###Example 2: Fuel Gauge
+This file demonstrates the simple API of the SparkFun MAX17043 Arduino library. 
+
+The code for this example can be found in the [Firmware](../Firmware/Example2_FuelGauge/) folder of this repository. Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch: 
+
+You will also need to install the SparkFun MAX1704x Fuel Gauge Arduino Library if you haven't already. You can click the link from within the code or you can download the zip from [the GitHub Repository](https://github.com/sparkfun/SparkFun_MAX1704x_Fuel_Gauge_Arduino_Library/archive/refs/heads/main.zip)
+
+<figure markdown>
+[![SparkFun MAX1704x Fuel Gauge Arduino Library Install](assets/img/MAX17043LibraryInstall.png){ width="90%" }](assets/img/MAX17043LibraryInstall.png "Click to enlarge")
+<figcaption markdown>SparkFun MAX1704x Fuel Gauge Arduino Library Install</figcaption>
+</figure>
+
+
+Make sure you've selected the correct board and port in the Tools menu and then hit the upload button. Once the code has finished uploading, go ahead and open a [Serial Monitor](https://learn.sparkfun.com/tutorials/terminal-basics) at 115200 baud. You should see the gauge's voltage and state-of-charge (SOC) readings, similar to the following: 
+
+<figure markdown>
+[![Arduino Example 2 Output](assets/img/Example2_Output.jpg){ width="90%" }](assets/img/Example2_Output.jpg "Click to enlarge")
+<figcaption markdown>Example 2 Output</figcaption>
+</figure>
+
+
+
+###Example 3: Display
+
+This example demonstrates how to display on the 1.3" OLED and read the fuel gauge. You should have the Portability Shield connected to the RTK Postcard or other controller. 
+
+The code for this example can be found in the [Firmware](../Firmware/Example3_Display/) folder of this repository. Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch: 
+
+You will also need to install the SparkFun Qwiic OLED Arduino Library if you haven't already. You can click the link from within the code or you can download the zip from [the GitHub Repository](https://github.com/sparkfun/SparkFun_Qwiic_OLED_Arduino_Library/archive/refs/heads/main.zip)
+
+
+Make sure you've selected the correct board and port in the Tools menu and then hit the upload button. Once the code has finished uploading, you should see the gauge's voltage and state-of-charge (SOC) readings, similar to the following: 
+
+<figure markdown>
+[![Arduino Example 3 Output](assets/img/Example3_Output.jpg){ width="90%" }](assets/img/Example3_Output.jpg "Click to enlarge")
+<figcaption markdown>Example 3 Output</figcaption>
+</figure>
+
+
+
+
+###Example 4: SD Card
+
+This example will mount an SD card, analyze the type of card, and output the analysis via the Serial Monitor. 
+
+Go ahead and connect the Portability Shield to the RTK Postcard or other controller board. Insert a microSD card into the socket. Cards up to 512GB should work.
+
+The code for this example can be found in the [Firmware](../Firmware/Example4_SD/) folder of this repository. Alternatively, you can expand the link below and copy and paste the code into a shiny new Arduino sketch: 
+
+
+
+
+
+Make sure you've selected the correct board and port in the Tools menu and then hit the upload button. Once the code has finished uploading, go ahead and open a [Serial Monitor](https://learn.sparkfun.com/tutorials/terminal-basics) at 115200 baud. 
+
+<figure markdown>
+[![Arduino Example 4 Output](assets/img/Example4_Output.jpg){ width="90%" }](assets/img/Example4_Output.jpg "Click to enlarge")
+<figcaption markdown>Example 4 Output</figcaption>
+</figure>

docs/github/contribute.md

@@ -4,7 +4,7 @@ Spot an improvement opportunity? Feel free to contribute to our open-source desi
 ## :material-file-document-multiple: Improve our Documentation
 All of this documentation can be modified by you! Please help us make it better.
 
-* These pages are contained in the [`docs` folder](https://github.com/sparkfun/SparkFun_Portability_Shield/tree/main/docs) of the [SparkFun Portability Shield repository](https://github.com/sparkfun/https://github.com/sparkfun/SparkFun_Portability_Shield/tree/main).
+* These pages are contained in the [`docs` folder](https://github.com/sparkfun/SparkFun_Portability_Shield/tree/main/docs) of the [SparkFun Portability Shield repository](https://github.com/sparkfun/SparkFun_Portability_Shield/tree/main).
 
 <!-- ### :material-source-pull:&nbsp;Submit a Correction -->
 ### Submit a Correction

docs/hard_copy.md

@@ -0,0 +1,9 @@
+---
+icon: material/book-open-variant
+---
+
+Need to download or print our hookup guide?
+
+* [Print :fontawesome-solid-print:](single_page.md) (Single-Page View)
+    * To save as a `*.pdf` file, select the **Printer** or **Destination** labeled ++"Save as PDF"++. *(Instructions will vary based on the browser)*
+<!-- * [Download :fontawesome-regular-file-pdf:](../board_files/hookup_guide.pdf) *(Beta - demonstration only)* -->

docs/hardware_overview.md

@@ -3,7 +3,7 @@ icon: material/cog
 ---
 
 ## OLED
-The 1.3" OLED is a small, monochrome, blue on black display with a 128 x 64 dot matrix panel and an 7-bit unshifted I<sup>2</sup>C address of 0x3D. For more information, refer to the [datasheet](https://cdn.sparkfun.com/assets/learn_tutorials/3/0/8/SSD1306.pdf).
+The 1.3" OLED is a small, monochrome, blue on black display with a 128 x 64 dot matrix panel and a 7-bit unshifted I<sup>2</sup>C address of 0x3D. To change the I<sup>2</sup>C address to 0x3C, cut the D/C jumper on the back of the board. For more information, refer to the [datasheet](https://cdn.sparkfun.com/assets/learn_tutorials/3/0/8/SSD1306.pdf).
 
 <figure markdown>
 [![1.3" OLED Screen](assets/img/27510-Portability-Shield_OLED.jpg){ width="75%" }](assets/img/27510-Portability-Shield_OLED.jpg "Click to enlarge")
@@ -13,20 +13,20 @@ The 1.3" OLED is a small, monochrome, blue on black display with a 128 x 64 dot
 
 
 
-## D-Pad
+## Navigation Switch
 
-The D-Pad allows for navigation of the configuration modes and menus related to the RTK or other loaded software. 
+The Navigation Switch allows for navigation of the configuration modes and menus related to the RTK or other loaded software. 
 
 <figure markdown>
-[![DPad](assets/img/27510-Portability-Shield_DPad.jpg){ width="75%" }](assets/img/27510-Portability-Shield_DPad.jpg "Click to enlarge")
-<figcaption markdown>DPad</figcaption>
+[![Navigation Switch](assets/img/27510-Portability-Shield_NavSwitch.jpg){ width="75%" }](assets/img/27510-Portability-Shield_NavSwitch.jpg "Click to enlarge")
+<figcaption markdown>Navigation Switch</figcaption>
 </figure>
 
 
 
 ## GPIO Expander
 
-The GPIO expander is used for D-Pad functionality and SD card detection. The 7-bit Unshifted Address is 0x18.
+The TCA9554 GPIO Expander is used for I<sup>2</sup>C interfacing with the Navigation Switch, 1.3" OLED display, the fuel gauge, and the SD Card Detect. Its 7-bit unshifted address is 0x20.
 
 <figure markdown>
 [![GPIO Expander](assets/img/27510-Portability-Shield_GPIOExpander.jpg){ width="75%" }](assets/img/27510-Portability-Shield_GPIOExpander.jpg "Click to enlarge")
@@ -65,7 +65,7 @@ How handy! There is an On/Off switch at the top of the board.
 
 ## Fuel Gauge
 
-The MAX17048 uses the Li+ battery-modeling algorithm ModelGauge™ to track the battery relative state-ofcharge (SOC) continuously over widely varying charge and discharge conditions. This eliminates current-sense resistor and battery learn cycles required in traditional fuel gauges and allows for the most accurate battery percentage readings. It's 7-bit unshifted address is 0x36. For more information, you can refer to the [datasheet](https://cdn.sparkfun.com/assets/5/2/7/6/6/MAX17048-MAX17049.pdf). 
+The MAX17048 uses the Li+ battery-modeling algorithm ModelGauge™ to track the battery relative state-of-charge (SOC) continuously over widely varying charge and discharge conditions. This eliminates current-sense resistor and battery learn cycles required in traditional fuel gauges and allows for the most accurate battery percentage readings. Its 7-bit unshifted address is 0x36. For more information, you can refer to the [datasheet](https://cdn.sparkfun.com/assets/5/2/7/6/6/MAX17048-MAX17049.pdf). 
 
 <figure markdown>
 [![Fuel Gauge](assets/img/27510-Portability-Shield_FuelGauge.jpg){ width="75%" }](assets/img/27510-Portability-Shield_FuelGauge.jpg "Click to enlarge")
@@ -85,7 +85,7 @@ The charge circuit charges Li+ batteries at 500mA. The equation below shows our
 
 ## MicroSD Card
 
-The microSD card slot allows for data logging or easy upload of programming files. 
+The microSD Socket Friction Fit slot allows for data logging or easy upload of programming files. 
 
 !!! warning
 	Do NOT drive the microSD card pins high if the card is not powered. Damage could occur! 

docs/introduction.md

@@ -15,7 +15,9 @@ icon: material/book-open-page-variant
     ![Product Thumbnail](assets/img/27510-Portability-Shield-Feature.jpg)
     </figure></a>
 
-- A small board that adds a display, navigation, logging, and battery management.
+- The SparkFun Portability Shield adds all the user interface bits needed to take a SparkFun dev board into the field. A LiPo battery connector, charger, fuel gauge, and an on/off switch take care of your power needs. A friction-fit microSD connector allow for datalogging. The 1.3" OLED and a 5-way navigation switch allow for an excellent user interface. Locking 0.1" headers along the edge of the shield make it easier to solder male pins in place.
+
+    I<sup>2</sup>C is used to interface to the display, fuel gauge, and the 5 way navigation switch (GPIO expander PCA9554), SPI is used to communicate with the microSD card. The power switch uses an ideal diode (LM66200) to disconnect the battery from the system for a sleep current of approximately 4μA.
 
 
 <center>
@@ -39,7 +41,7 @@ To follow along with this tutorial, you will need the following materials. You m
         </td>
         <td>
             <a href="https://www.sparkfun.com/products/26916">
-                <center><img src="" style="width:140px; height:140px; object-fit:contain;" alt="RTK Postcard"></center>
+                <center><img src="https://cdn.sparkfun.com/r/600-600/assets/parts/2/8/0/3/2/SparkFun_RTK_Postcard-angled.jpg" style="width:140px; height:140px; object-fit:contain;" alt="RTK Postcard"></center>
                 <h3 class="title">SparkFun RTK Postcard</h3>
             </a>
             GPS-26916
@@ -49,8 +51,6 @@ To follow along with this tutorial, you will need the following materials. You m
 
 
 
-
-
 ## Suggested Reading
 
 Below are a few tutorials that may help users familiarize themselves with various aspects of the board.
@@ -64,6 +64,13 @@ Below are a few tutorials that may help users familiarize themselves with variou
     </a>
     <a href="https://learn.sparkfun.com/tutorials/what-is-gps-rtk">**What is GPS RTK**
     </a>
+-   <a href="https://docs.sparkfun.com/SparkFun_RTK_Firmware/">
+    <figure markdown>
+    ![SparkFun RTK Product Manual](https://cdn.sparkfun.com/assets/learn_tutorials/2/1/8/8/SparkFun_RTK_Facet_-_Hookup_Guide_Preview.jpg)
+    </figure>
+    </a>
+    <a href="https://docs.sparkfun.com/SparkFun_RTK_Firmware/">**SparkFun RTK Product Manual**
+    </a>
 
 </div>
 

docs/resources.md

@@ -6,5 +6,5 @@ For more resources related to the SparkFun Portability Shield, check out the lin
 * [Product Page](https://www.sparkfun.com/products/27510)
 * [Schematic](assets/board_files/SparkFun_Portability_Shield_Schematic.pdf) (PDF)
 * [KiCad Files](assets/board_files/SparkFun_Portability_Shield_KiCadFiles.zip) (ZIP)
-* [Board Dimensions](assets/img/SparkFun_Portability_Shield_BoardDimensions.jpg)
+* [Board Dimensions](assets/board_files/SparkFun_Portability_Shield_BoardDimensions.jpg)
 * [Hardware GitHub Respository](https://github.com/sparkfun/SparkFun_Portability_Shield)

docs/single_page.md

@@ -14,12 +14,6 @@ icon: fontawesome/solid/scroll
 # Hardware Assembly
 --8<-- "./docs/hardware_assembly.md:5"
 
-## Software Setup
---8<-- "./docs/software_setup_and_programming.md:5"
-
-## Arduino Example
---8<-- "./docs/arduino_example.md:5"
-
 # Troubleshooting Tips
 --8<-- "./docs/troubleshooting.md:5"