136 8 documentation + token generator testing code (#137)

* Add script to create custom OpenPAYGO tokens

* Add documentation of OpenPAYGO token generation

* Moved Getting Started documentation to quick-start-guide.md

* Refactoring of `opaygo_functions` (#138)

* Refactoring of opaygo_functions

* formaat document

* Revert changes to `lib`

* Whitespace changes

---------

Co-authored-by: Peguy-WANDA <peguywanda@gmail.com>

* Refactor the Github Actions setup (#139)

* Refactor the Github Actions setup

* Update Github Actions workflow name

* Fix Markdown lint

* Fix more Markdownlint

* Fix Markdownlint

* One more

* Fix `yamllint`

* Fix shields

* Reformatting with Black tool

* Linting

* Moved Excel sheet to documentation

* Lint

---------

Co-authored-by: MichelFripiat <fripiat.m@solarly.energy>
Co-authored-by: Daniel Mohns <dmohns@users.noreply.github.com>
Co-authored-by: Peguy-WANDA <peguywanda@gmail.com>
Co-authored-by: Daniel Mohns <daniel.mohns@posteo.de>

.gitignore

@@ -36,3 +36,4 @@ fp-info-cache
 .DS_Store
 .pio/
 .vscode/
+.idea/

docs/quick-start-guide.md

@@ -0,0 +1,41 @@
+# Getting Started
+
+You have now an OpenSmartMeter in your hands and you want to test it? Here is how.
+
+## Initial configuration
+
+ToDo: Do a tutorial on how to access the technical mode via the keypad of the OpenSmartMeter. Make pictures of the OSM.
+
+ToDo: How to set up secret key, starting code, etc.
+
+## Testing OpenPAYGO tokens
+
+After plugging the OSM, it will appear the following screen:
+ToDo: Provide a picture
+
+By default, the OSM is deactivated, which means it doesn't provide any energy in its output.
+If the initial default configuration has been applied, you can test tokens available here:
+
+**Default configuration:**
+Starting Code: 407592873
+Secret Key: 47a01268b629e1b027fe20c99309643f
+
+| Time/Energy     | Serial OSM10000001 |
+| --------------- | ------------------ |
+| add 1 day/kWh   | 287 923 874        |
+| add 30 days/kWh | 743 630 903        |
+| set 7 days/kWh  | 844 231 880        |
+| unlock forever  | 304 054 873        |
+
+Remark:
+
+- We cannot jump back to a previous token if a later token has been already entered.
+
+If you want to create other tokens:
+
+1. Open the repository on an IDE with python3.9 or above.
+2. Install the Python requirements (in OpenSmartMeter/firmware/test):
+   pip3 install -r requirements.txt
+3. Change initial parameters in "test_openpaygo.py"
+   Token_value can be days or kWh, depending on the initial default configuration you have defined on the OSM itself.
+4. Run the script and get your desired token in the console output.

firmware/test/model.py

@@ -0,0 +1,8 @@
+class Device(object):
+    def __init__(self, device_settings):
+        self.serial = device_settings.get("serial", None)
+        self.starting_code = device_settings.get("starting_code", None)
+        self.secret_key = device_settings.get("secret_key", None)
+        self.restricted_digit_set = device_settings.get("restricted_digit_set", None)
+        self.value_divider = device_settings.get("value_divider", None)
+        self.count = device_settings.get("count", None)

firmware/test/requirements.txt

@@ -0,0 +1 @@
+openpaygo

firmware/test/test_openpaygo.py

@@ -0,0 +1,29 @@
+from openpaygo import generate_token, TokenType
+from firmware.test.model import Device
+
+# Device definition
+device_settings = {
+    "serial": "OSM10000001",
+    "starting_code": 407592873,
+    "secret_key": "47a01268b629e1b027fe20c99309643f",
+    "restricted_digit_set": False,
+    "value_divider": 1,
+    "count": 0,
+}
+# Token definition
+token_type = TokenType.ADD_TIME  # ADD_TIME, SET_TIME, DISABLE_PAYG
+token_value = 7  # Set to 0 if DISABLE_PAYG
+
+# We get the new token and update the count
+device = Device(device_settings)
+device.count, new_token = generate_token(
+    secret_key=device.secret_key,
+    count=device.count,
+    value=token_value,
+    token_type=TokenType.ADD_TIME,
+    starting_code=device.starting_code,
+    value_divider=device.value_divider,
+    restricted_digit_set=device.restricted_digit_set,
+)
+
+print("Token: " + new_token)

mkdocs.yml

@@ -114,6 +114,7 @@ extra_javascript:
 # Page tree
 nav:
   - Home: index.md
+  - Quick-start guide: quick-start-guide.md
   - Firmware Documentation:
       - Firmware Design: firmware/design.md
       - Calibration: firmware/calibration.md