Release for version 0.2.1 (#3)

Co-authored-by: Synaptics GitLab CI <[email protected]>

Author: vikram-rana-synaptics

.github/workflows/prepare-release.yml

@@ -0,0 +1,31 @@
+name: Prepare release pull request
+
+on:
+  push:
+    branches:
+      - documentation/release/*
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  create-pull-request:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip setuptools wheel
+          pip install --upgrade --requirement docs/requirements.txt
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Create pull request
+        run: gh pr create --base main --head ${{ github.ref_name }} --fill --label documentation || gh pr edit --add-label documentation
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.gitlab-ci.yml

@@ -0,0 +1,53 @@
+image: python:3.12
+
+build:
+  stage: build
+  before_script:
+    - python --version ; pip --version  # For debugging
+    - pip install virtualenv
+    - virtualenv venv
+    - source venv/bin/activate
+  script:
+    - pip install sphinx sphinx-rtd-theme
+    - sphinx-build docs build
+  rules:
+    - if: $CI_COMMIT_BRANCH !~ /documentation.*/ # Don't build on documentation branches.
+
+prepare_release:
+  stage: deploy
+  before_script:
+    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'  # Ensure ssh-agent is installed and running
+    - eval $(ssh-agent -s)
+    - ssh-add -L || true
+    - chmod 400 "$GITLAB_DEPLOY_KEY"  # Add ssh deploy keys
+    - chmod 400 "$GITHUB_DEPLOY_KEY"
+    - mkdir -p ~/.ssh
+    - chmod 700 ~/.ssh
+    - echo 'echo $GITLAB_DEPLOY_PASSPHRASE' > ~/.ssh/gitlab_passphrase && chmod 700 ~/.ssh/gitlab_passphrase
+    - echo 'echo $GITHUB_DEPLOY_PASSPHRASE' > ~/.ssh/github_passphrase && chmod 700 ~/.ssh/github_passphrase
+    - DISPLAY=None SSH_ASKPASS=~/.ssh/gitlab_passphrase ssh-add "$GITLAB_DEPLOY_KEY"
+    - DISPLAY=None SSH_ASKPASS=~/.ssh/github_passphrase ssh-add "$GITHUB_DEPLOY_KEY"
+    - ssh-add -L
+    - rm ~/.ssh/*passphrase
+    - touch ~/.ssh/known_hosts  # Add known ssh hosts
+    - echo "$GITLAB_KNOWN_HOSTS" >> ~/.ssh/known_hosts
+    - echo "$GITHUB_KNOWN_HOSTS" >> ~/.ssh/known_hosts
+    - git version  # Set up git credentials
+    - git config --global user.email "$GIT_EMAIL"
+    - git config --global user.name "$GIT_USERNAME"
+  script:
+    - git status
+    - 'git for-each-ref --count=2 --sort=-creatordate --format "%(refname)" refs/tags/[0-9]*\.[0-9]*\.[0-9]* | sed "s=refs/tags/=="'
+    - '{ IFS= read -r new_version && IFS= read -r old_version; } < <(git for-each-ref --count=2 --sort=-creatordate --format "%(refname)" refs/tags/[0-9]*\.[0-9]*\.[0-9]* | sed "s=refs/tags/==")'
+    - 'echo "New version: $new_version"'
+    - 'echo "Old version: $old_version"'
+    - git remote add gitlab "$GITLAB_URL"
+    - git remote add github "$GITHUB_URL"
+    - git fetch --all
+    - git reset --soft github/main
+    - git commit -m "Release for version $new_version"
+    - git push --verbose --push-option ci.skip gitlab "HEAD:refs/heads/documentation/release/$new_version"  # Skip ci to avoid potential infinite recursion loop on ci builds
+    - git push --verbose github "HEAD:refs/heads/documentation/release/$new_version"
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/'  # Bit OTT but semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+

docs/conf.py

@@ -45,6 +45,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
@@ -181,3 +182,8 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ("https://docs.python.org/3.5", None)}
+
+# External weblinks
+extlinks = {
+    "githubSamples": ('https://github.com/DisplayLink/dl-7450/tree/main/%s', None)
+}

docs/dl_7450/quickstart.rst

@@ -21,27 +21,29 @@ shown on the screen should match the sticker on the DL-7450 board.
 
 .. image:: ../images/start_screen.png
 
-
-You should have received an archive file called *dl7450-samples.tgz*. Expand this archive:
-
-.. image:: ../images/samples.png
-
-The resulting files consist of some sample applications and README documents
-that show how to create some simple applications that will run on the DL-7450.
-
-To send code to the dock we have provided a ``send_code.py`` python script, located
-in the *scripts* directory, to run this you will need some flavour of python 3
-installed, and the ``requests`` package installed. The script has been tested against versions 3.8 and 3.12.
-
-For example, when running from the root folder of that archive::
+The DL-7450 SDK includes a set of sample code availabe to download
+:githubSamples:`here <samples>`. These, or your own bespoke applications can be
+sent to the dock via a REST API. We have provided a script, ``send_code.py``
+available :githubSamples:`here <scripts/send_code.py>`. To run this you will
+need some flavour of python 3 installed, and the ``requests`` package
+installed. You will also need the application key and secret and your
+enterprise ID and the DL-7450 ID, which you should have received with your
+reference board. For example, to run the :githubSamples:`carousel application
+<samples/http/carousel.py>`::
 
     python ./scripts/send_code.py \
       --key 241FB8AF5E23E00406E985E6-My-Application \
       --secret 3334e363-efd2-a764-e789-d7daf71245f9  \
       --enterprise 4d0ec8a128f9a6814acf8a96 \
       --dock A7BBAFE26E7E94EE650DD9AC039EBC4569265A8EAD08A7F8BA1AAFFFF21523B \
-      --file ./samples/http/carousel.py
+      --file carousel.py
+
+You can now start to develop your own DL-7450 applications.  
 
-.. warning::
-   In Windows there is a length limit on the filesystem. If you hit any ``FileNotFoundError: [Errno 2] No such file or directory:``
-   errors, be careful to check the path is not exceeding that limit - or turn the limit off.
+.. note::
+   The DL-7450 reference boards are shipped with the read-only `datastore`
+   populated with the :githubSamples:`default application
+   <samples/introduction/default.py>`, and some `ImageStore` images and
+   `KvStore` data to support the :githubSamples:`sample applications
+   <samples>`. You are free to change the contents of the read-only store
+   during development. Details can be found in the `datastore` documentation.

docs/library/datastore.rst

@@ -6,52 +6,108 @@
 .. module:: datastore
    :synopsis: Data persistence services
 
-.. admonition:: Coming soon
-   :class: tip
-
-   In this preview only data that has been saved in the factory data store is available for retrieval. For
-   the workshop, we have populated the ImageStore with several splashscreen background images.
-
-This module contains classes for managing storage and retrieval of application data. Persistent application
-data is of two possible types:
-
-   - *Factory settings:* Manufacturers can provision the DL-7450 with application data in the manufacturing 
-     process, such as branded splashscreen backgrounds or the URL of a content provider. It
-     is also possible to provide unique-per-dock (UPD) data, such as enrolment tokens for IoT cloud service
-     providers.
-   - *Runtime settings:* Applications may store data that is not set in the factory, but which persists across
-     DL-7450 restarts. Such data may include access tokens for cloud providers or local network settings
-     that have been provisioned remotely after the dock has been deployed in an enterprise setting.
+This module contains classes for managing storage and retrieval of application
+data. Logically, the DL-7450 :py:mod:`datastore` is a single entity, with
+different partitions. There is an :py:class:`ImageStore` interface for
+retreiving images from the persistent data store. The image data is available
+as a python `bytearray` and the type is identified by one of the image type
+constants from the :py:mod:`image` module. Alternatively, a token may be used
+for later retreiving an image. This may reduce the number of copies of the
+image data created and used by your application. Simple key-value pairs can be
+stored and retrieved using the :py:class:`KvStore` interface. The python
+application itself also resides in the datastore, but is not explicitly
+accessible from the application. In later releases of the SDK, storage for
+futher types, such as fonts will be provided.
+
+Data may also be stored in different ways. Persistent application data is of
+two possible types:
+
+   - *Factory settings* or *Read-only memory (ROM)* storage. Manufacturers can
+     provision the DL-7450 with application data in the manufacturing process,
+     such as branded splashscreen backgrounds or the URL of a content provider.
+     It is also possible to provide unique-per-dock (UPD) data, such as
+     enrolment tokens for IoT cloud service providers.
+   - *Runtime settings:* Applications may store data that is not set in the
+     factory, but which persists across DL-7450 restarts. Such data may include
+     access tokens for cloud providers or local network settings that have been
+     provisioned remotely after the dock has been deployed in an enterprise
+     setting.
 
 There is an additional non-persistent storage type:
 
-   - *Ephemeral settings:* Applications may store data that is useful at runtime, but is not essential to 
-     store across dock restarts. For example, image data can be large, and it is not possible to keep many
-     on the Python runtime memory heap. In this case an application can store them in out-of-process memory
-     and retrieve them on demand. An example use-case is using the ephemeral storage area to avoid having
-     to make slow HTTP requests to obtain subsequent data. 
-
-There is an :py:class:`ImageStore` interface for retreiving images from the persistent data stores. The image
-data is available as a python `bytearray` and the type is identified by one of the image type constants from the
-:py:mod:`image` module. Alternatively, a token may be used for later retreiving an image. This may reduce the number
-of copies of the image data created and used by your application.
-
-Simple key-value pairs can be stored and retrieved using the :py:class:`KvStore` interface.
-
-
-Constants
----------
-
-.. data:: datastore.FACTORY_DATA
-          datastore.APPLICATION_DATA
-
-   Pick whether to use application data or factory data.
-
-.. admonition:: Coming soon
+   - *Ephemeral settings:* Applications may store data that is useful at
+     runtime, but is not essential to store across dock restarts. For example,
+     image data can be large, and it is not possible to keep many on the Python
+     runtime memory storage. In this case an application can store them in
+     out-of-process memory and retrieve them on demand. An example use-case is
+     using the ephemeral storage area to avoid having to make slow HTTP
+     requests to obtain subsequent data. 
+
+When an application requests an item from the datastore, unless explicitly
+stated otherwise, there is an order of preference. For example if the
+application requests a splashscreen background with image tag *default_img*,
+first the ephemeral store will be checked, followed by the runtime store and
+finally the ROM/factory store. 
+
+The amounts available for different types of data is currently as follows.
+There is no restriction on how data is distributed across the available
+storage, i.e. an applicaiton developer can use it as they see fit for code,
+images and key-value data.
+
+   +--------------+----------------------------+
+   | Data Storage | Available                  |
+   +==============+============================+
+   | Factory/ROM  | 13MB                       |
+   +--------------+----------------------------+
+   | Runtime      | 13MB                       |
+   +--------------+----------------------------+
+   | Ephemeral    | 128MB                      |
+   +--------------+----------------------------+
+
+
+.. admonition:: Not-yet implemented
    :class: tip
 
-   These constants aren't available in this preview,
-   and all data retrieval is from the factory data store.
+   In the present version of the DL-7450 SDK only the application ROM store is
+   implemented. 
+
+
+
+Application ROM Storage during development
+------------------------------------------
+
+The Application ROM storage area, also referred to as *Factory storage*
+provides a mechanism to deploy a customer application and associated data in
+the manufacturing process. This enables the customer's DL-7450 dock to run the
+customer application on first boot after sale to the end user. The semantics of
+the application ROM store is as suggested by the name, a read-only data store.
+This supports a factory-reset operation on the dock. One usage pattern might be
+for a customer to ship a dock with a basic application in factory storage,
+which bootstraps another application that requires user-specific data in the
+field. Another usage pattern is that the application ROM store contains version
+N of the application, which can be updated to a later version which is stored
+in the runtime store. Yet another case is that the factory application might
+provide corporate imagery of the dock manufacturer, which can be overridden in
+the field by corporate imagery of the end-user. In all cases, a a factory reset
+will cause the application and its data to be restored to the state that it was
+manufactured in. 
+
+Therefore, the :py:mod:`datastore` APIs in the DL-7450 SDK do not allow the ROM store
+area to be written to. While this is the required behaviour in a production
+docking station, it is too restrictive for development. To support development,
+DisplayLink has provided a REST API in our development cloud to populate the
+factory store. The details are provided with the :githubSamples:`supporting
+scripts </scripts/README.md>`. Note that the operation is atomic and
+destructive - i.e. the application ROM store is replaced in a single operation.
+This mechanism will not be available to docks in production.
+
+Ephemeral application code during development
+---------------------------------------------
+
+To support development, DisplayLink provides a REST API to deploy new
+application code immediately to the dock. This makes use of ephemeral data
+storage. The details of how to use this API are given with the
+:githubSamples:`supporting scripts </scripts/README.md>`. 
 
 
 Classes

docs/library/dock.DockInfo.rst

@@ -51,11 +51,6 @@ Methods
 
    Returns one of the constants described below.
 
-.. admonition:: Coming soon
-   :class: tip
-
-   The return value will always be `DockInfo.HOST_NOT_CONNECTED` in this preview.
-
 Constants
 ---------
 

docs/library/mqtt.Client.rst

@@ -81,15 +81,47 @@ application through relevant callbacks about MQTT events.
     asynchronously, when the connection is established, or when a connection
     cannot be established for some reason. 
 
-    Example callback function::
+
+    It is important to note that the *on_connect* callback can be called
+    multiple times. In particular if a connection is made successfully, but is
+    later lost, the callback will be invoked twice, the second time as a
+    failure. The MQTT will *automatically attempt to reconnect to the broker*.
+    If this reconnection attempt is successful, yet another invocation of the
+    *on_connect* callback will occur. 
+
+    Example 1: the Client attempts to connect to the server, but does not
+    provide the correct username and password. The *on_connect* callback will
+    be invoked with status = 4. No further connection attempt will be made, and
+    the failure is permanent.
+
+    Example 2: the client connects successfully. The *on_connect* callback is
+    invoked with status = 0. Some time later, the local network is becomes
+    unavailable. On the next failed ping attempt (see the *keepAlive* option),
+    the *on_connect* callback is invoked with status = -1. However, the client
+    will attempt to reconnect to the broker. The first attempt is after 1
+    seconds, then 2, 4, 8, 16 and 32 seconds subsequently, and from then every
+    1 minute. When the network is available again, and the client reconnects,
+    the *on_connect* callback is invoked again with status = 0.
+
+    It is advisable for the application to keep track of the connection status.
+    An example of an *on_connect* callback::
+
+      connected = False
 
       def on_connect(rc, flags):
         if rc == 0:
           # connection accepted by the broker
+          connected = True
         else:
-          errMsg = mqtt.ErrorDescription(rc)
-          # report or handle error.
-
+          if rc > 0:
+            # permanent failure...
+          if rc < 0: 
+            connected = False
+            errMsg = mqtt.ErrorDescription(rc)
+            if connected: 
+              # connection lost. Reconnect attempt follows
+            else:
+              # report or handle error. Reconnect attempt follows
 
     *options* is a dictionary that contains a variety of optional parameters
     for this connection. The possible key-value pairs are described below. All
@@ -148,6 +180,12 @@ application through relevant callbacks about MQTT events.
       The *clean_session* option is currently set to 0 and cannot be changed in
       this version of the DL-7450 SDK.
 
+      The client automatically attempts to reconnect to the broker when a
+      connection attempt fails. The minimum time for the retry is 1 second. If
+      this fails, the next retry is 2 seconds, so on through 4, 8, 16 and 32
+      seconds. After that, further attempts occur every minute. This procedure
+      resets once a successful connection is made. 
+
   .. method:: publish(topic, message, qos)
 
      This method initiates the publication of a message to the broker. The

docs/templates/layout.html

@@ -14,12 +14,10 @@
   {% else %}
     <div class="wy-alert wy-alert-danger">
       <p>
-				The information contained in this website is Synaptics confidential
-				information, and is made available to you under the terms of our
-				Non-Disclosure Agreement (NDA).  This is a preview version of the
-				DisplayLink DL-7450 Software Development Kit Documentation. The
-				functionality that is described and made available in this version is
-				subject to addition, removal or change without warning.
+				This is a preview version of the DisplayLink DL-7450 Software
+				Development Kit Documentation. The functionality that is described and
+				made available in this version is subject to addition, removal or
+				change without warning.
       </p>
     </div>
   {% endif %}