From ad8957afbb0dd92dae4eebff2347c3fa52c1e2e1 Mon Sep 17 00:00:00 2001
From: Floris Lambrechts <florisla@gmail.com>
Date: Mon, 28 Feb 2022 12:52:31 +0100
Subject: [PATCH] docs: Describe the various ways to start stm32loader

---
 RUN.md              | 52 +++++++++++++++++++++++++++++++++++++++++++++
 stm32loader/main.py |  3 ++-
 stm32loader/uart.py |  7 ++++++
 3 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/RUN.md b/RUN.md
index e69de29..f33ec11 100644
--- a/RUN.md
+++ b/RUN.md
@@ -0,0 +1,52 @@
+
+# Running stm32loader
+
+
+## Execute as a module
+
+After installing stm32loader with `pip`, it's available as a Python module.
+
+You can execute this with `python -m [modulename]`.
+
+```shell
+python3 -m stm32loader
+```
+
+
+## Execute as a module without installing
+
+You can also run `stm32loader` without installing it.  You do need `pyserial` though.
+
+Make sure you are in the root of the repository, or the repository is in `PYTHONPATH`.
+
+```shell
+python3 -m pip install pyserial --user
+python3 -m stm32loader
+```
+
+
+## Execute main.py directly
+
+The file `main.py` also runs the `stm32loader` program when executed.
+Make sure the module can be found; add the folder of the repository to `PYTHONPATH`.
+
+```shell
+PYTHONPATH=. python3 stm32loader/main.py
+```
+
+
+## Use from Python
+
+You can use the classes of `stm32loader` from a Python script.
+
+Example:
+
+```python
+from stm32loader.main import Stm32Loader
+
+loader = Stm32Loader()
+loader.configuration.port = "/dev/cu.usbserial-A5XK3RJT"
+loader.connect()
+loader.stm32.readout_unprotect()
+loader.disconnect()
+```
diff --git a/stm32loader/main.py b/stm32loader/main.py
index 174d004..e6ab455 100644
--- a/stm32loader/main.py
+++ b/stm32loader/main.py
@@ -26,6 +26,7 @@
 import copy
 import os
 import sys
+from types import SimpleNamespace
 
 try:
     from progress.bar import ChargingBar as progress_bar
@@ -71,7 +72,7 @@ class Stm32Loader:
     def __init__(self):
         """Construct Stm32Loader object with default settings."""
         self.stm32 = None
-        self.configuration = None
+        self.configuration = SimpleNamespace()
 
     def debug(self, level, message):
         """Log a message to stderror if its level is low enough."""
diff --git a/stm32loader/uart.py b/stm32loader/uart.py
index fc0df3a..49d07dc 100644
--- a/stm32loader/uart.py
+++ b/stm32loader/uart.py
@@ -77,6 +77,13 @@ def connect(self):
             timeout=self._timeout,
         )
 
+    def disconnect(self):
+        if not self.serial_connection:
+            return
+
+        self.serial_connection.close()
+        self.serial_connection = None
+
     def write(self, *args, **kwargs):
         """Write the given data to the serial connection."""
         return self.serial_connection.write(*args, **kwargs)