From da68dcf995fa5b211de750a7574821aa178ee084 Mon Sep 17 00:00:00 2001
From: Brad Campbell <bradjc5@gmail.com>
Date: Tue, 7 May 2024 11:30:32 -0400
Subject: [PATCH] update docs

---
 docs/display.md    | 106 +++++++++++++++++++++++++++++++++++++++++++++
 docs/helpers.md    |   2 +-
 docs/index.md      |  19 +++++++-
 docs/tbfh.md       |  27 ++++++++++++
 docs/tockloader.md |   6 ++-
 5 files changed, 157 insertions(+), 3 deletions(-)

diff --git a/docs/display.md b/docs/display.md
index 52263ae..2c3bc83 100644
--- a/docs/display.md
+++ b/docs/display.md
@@ -158,6 +158,15 @@ def show_app_map(self, apps, start_address)
 
 
 
+### show\_board\_visual
+```py
+
+def show_board_visual(self, apps)
+
+```
+
+
+
 
 
 ## Class JSONDisplay
@@ -233,3 +242,100 @@ Show the key value pairs for a list of attributes.
 
 
 
+
+## Class VisualDisplay
+Format output as an ASCII art string.
+
+┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┐
+│         | │         | │         | │       |
+│         | │         | │         | │       |
+│         | │         | │         | │       |
+│ version | │ version | │ version | │ blink |
+│         | │         | │         | │       |
+│         | │         | │         | │       |
+│         | │         | │         | │       |
+│         | │         | │         | │       |
+└─────────┘ └─────────┘ └─────────┘ └───────┘
+┌───────────────────────────────────────────┐
+│ Kernel                                    |
+└───────────────────────────────────────────┘
+### \_\_init\_\_
+```py
+
+def __init__(self)
+
+```
+
+
+
+Arguments:
+- show_headers: bool, if True, label each section in the display output.
+
+
+### bootloader\_version
+```py
+
+def bootloader_version(self, version)
+
+```
+
+
+
+Show the bootloader version stored in the bootloader itself.
+
+
+### get
+```py
+
+def get(self)
+
+```
+
+
+
+### kernel\_attributes
+```py
+
+def kernel_attributes(self, kern_attrs)
+
+```
+
+
+
+Show the kernel attributes stored in the kernel binary.
+
+
+### list\_apps
+```py
+
+def list_apps(self, apps, verbose, quiet)
+
+```
+
+
+
+Show information about a list of apps.
+
+
+### list\_attributes
+```py
+
+def list_attributes(self, attributes)
+
+```
+
+
+
+Show the key value pairs for a list of attributes.
+
+
+### \_width
+```py
+
+def _width(self)
+
+```
+
+
+
+
diff --git a/docs/helpers.md b/docs/helpers.md
index e71507a..fba82c0 100644
--- a/docs/helpers.md
+++ b/docs/helpers.md
@@ -218,7 +218,7 @@ Set a terminal title from a `pyserial` object.
 ### text\_in\_box
 ```py
 
-def text_in_box(string, box_width)
+def text_in_box(string, box_width, box_height=3)
 
 ```
 
diff --git a/docs/index.md b/docs/index.md
index 53aec13..095ff0e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,7 +6,8 @@ Install
 -------
 
 ```
-pip3 install tockloader --user
+pip3 install pipx
+pipx install tockloader
 ```
 
 If you want tab completions:
@@ -234,6 +235,17 @@ file to use.
     - `{address:#x}`: The specified address for the binary to be programmed at.
     - `{length}`: The number of bytes. Only valid for the `read` operation.
 
+For STM32 boards, Tockloader supports
+[STLINK](https://github.com/stlink-org/stlink). The stlink tool knows how to
+interface with the boards, so there are not many flags.
+
+    tockloader [command] --board [board] --arch [arch] --page-size [page_size] \
+                         --stlink \
+                         --stinfo-cmd [stinfo_cmd] --stflash-cmd [stflash_cmd]
+
+- `stinfo_cmd`: The st-info executable to invoke. Defaults to `st-info`.
+- `stflash_cmd`: The st-flash executable to invoke. Defaults to `st-flash`.
+
 Finally, Tockloader can treat a local file as though it were the flash contents
 of a board. The file can then be loaded separately onto a board.
 
@@ -363,3 +375,8 @@ directory:
     ./generate_docs.py
     cd ..
     mkdocs serve --dev-addr=0.0.0.0:8001
+
+### Create requirements.txt
+
+    pip3 install pipreqs
+    pipreqs . --force
diff --git a/docs/tbfh.md b/docs/tbfh.md
index 0b16222..0ece794 100644
--- a/docs/tbfh.md
+++ b/docs/tbfh.md
@@ -93,6 +93,15 @@ Try to shrink the footer `number_bytes`. Shrink as much as possible up
 to the number by removing padding.
 
 
+### to\_str\_at\_address
+```py
+
+def to_str_at_address(self, address)
+
+```
+
+
+
 ### verify\_credentials
 ```py
 
@@ -676,6 +685,15 @@ Set a flag in the TBF header.
 Valid flag names: `enable`, `sticky`
 
 
+### to\_str\_at\_address
+```py
+
+def to_str_at_address(self, address)
+
+```
+
+
+
 ### \_\_str\_\_
 ```py
 
@@ -1064,6 +1082,15 @@ Set a flag in the TBF header.
 Valid flag names: `enable`, `sticky`
 
 
+### to\_str\_at\_address
+```py
+
+def to_str_at_address(self, address)
+
+```
+
+
+
 ### \_\_str\_\_
 ```py
 
diff --git a/docs/tockloader.md b/docs/tockloader.md
index 87b7cb3..7e16a63 100644
--- a/docs/tockloader.md
+++ b/docs/tockloader.md
@@ -451,7 +451,7 @@ to effectively uninstall it.
 ### \_reshuffle\_apps
 ```py
 
-def _reshuffle_apps(self, apps)
+def _reshuffle_apps(self, apps, preserve_order=False)
 
 ```
 
@@ -464,6 +464,10 @@ This function is really the driver of tockloader, and is responsible for
 setting up applications in a way that can be successfully used by the
 board.
 
+If `preserve_order` is set to `True` this won't actually do any
+shuffling, and will instead load apps with padding in the order they are
+in the array.
+
 
 ### \_set\_attribute
 ```py