Skip to content

Commit b267e8d

Browse files
github-actions[bot]github-actions[bot]
authored
Documentation version 0.3.1 (#4)
1 parent a6cd57b commit b267e8d

22 files changed

+371
-196
lines changed

‎.github/workflows/prepare-release.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,9 @@ jobs:
2525
run: |
2626
sphinx-build docs _build
2727
- name: Create pull request
28-
run: gh pr create --base main --head ${{ github.ref_name }} --fill --label documentation || gh pr edit --add-label documentation
28+
run: |
29+
git fetch origin main
30+
gh pr create --base main --head ${{ github.ref_name }} --fill --label documentation || gh pr edit --add-label documentation
2931
env:
3032
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3133

‎.gitlab-ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ prepare_release:
4545
- git remote add github "$GITHUB_URL"
4646
- git fetch --all
4747
- git reset --soft github/main
48-
- git commit -m "Release for version $new_version"
48+
- git commit -m "Documentation version $new_version"
4949
- 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
5050
- git push --verbose github "HEAD:refs/heads/documentation/release/$new_version"
5151
rules:

‎docs/dl_7450/code.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ This is the correct form for transmitting the code to the dock via the ``docks\a
118118
119119
Send text message
120120
-----------------
121-
You can also send a text message to the dock. The message is displayed on the splashscreen. The message is sent to the ``docks\application\message`` endpoint. The request body should look like this:
121+
You can also send a text message to the dock. The message is displayed on the splash screen. The message is sent to the ``docks\application\message`` endpoint. The request body should look like this:
122122

123123
.. code-block:: python
124124
@@ -149,7 +149,7 @@ The ``scripts/send_text.py`` script can be used to send a text message to the do
149149
150150
Send image
151151
----------
152-
You can also send an image to the dock. The image is displayed on the splashscreen. The image is sent to the ``docks\application\image`` endpoint. The request body should look like this:
152+
You can also send an image to the dock. The image is displayed on the splash screen. The image is sent to the ``docks\application\image`` endpoint. The request body should look like this:
153153

154154
.. code-block:: python
155155

‎docs/dl_7450/paradigm.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
.. _dl_7450_paradigm:
2+
3+
Programming paradigm
4+
====================
5+
6+
When executing code on the DL-7450, the application runs using a
7+
single thread of execution. Whilst this thread (henceforth called
8+
the Python thread) executes, there are a number of actions that
9+
cannot be performed:
10+
11+
* The execution of any callbacks, whether they are timers set via
12+
:func:`wakeup`, responses from async :py:mod:`http` requests or
13+
responses to changes in the state of DL-7450 hardware (e.g.
14+
:py:mod:`gpio` pins).
15+
* The rendering of elements added, removed or modified on the
16+
:py:mod:`splashscreen`.
17+
18+
The use of `time.sleep` therefore is *highly* discouraged, as it
19+
will prevent any of these core SDK functionalities from occuring.
20+
21+
Instead, application developers are encouraged to write applications
22+
that react to events, using the main component of the app mostly to
23+
set up :py:class:`wakeup.Timer`\ s and other callbacks.
24+
25+
Once the Python thread finishes processing the Python code, it is
26+
now able to go idle and allow timers, callbacks and rendering to
27+
occur.
28+
29+
The use of dedicated callbacks where available is also highly
30+
encouraged over proactively polling state using a
31+
:py:class:`wakeup.Timer`; this will result in much more responsive
32+
applications.

‎docs/dl_7450/quickref.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,13 @@ Use the :ref:`DockControl <dock.DockControl>` class to control dock settings::
4141
Splashscreen control
4242
--------------------
4343

44-
Use the `splashscreen` module to control the splashscreen content::
44+
Use the `splashscreen` module to control the splash screen content::
4545

4646
from splashscreen import Splashscreen, Alignment
4747
import image
4848

49-
screen = Splashscreen() # create a splashscreen control interface
50-
screen.set_background(bg_image, image.PNG) # set the splashscreen background
49+
screen = Splashscreen() # create a splash screen control interface
50+
screen.set_background(bg_image, image.PNG) # set the splash screen background
5151
screen.add_text_box(["Hello, world"]) # create text box in default message position
5252

5353
text_attributes = { # control the position of text

‎docs/dl_7450/start.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@ Getting started
1212
security.rst
1313
tutorial.rst
1414
code.rst
15+
paradigm.rst
1516
quickref.rst
1617

‎docs/library/datastore.ImageStore.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,5 +31,5 @@ Methods
3131
Returns an opaque `image.ImageToken` that can be passed to :py:class:`splashscreen.Splashscreen` methods. Unlike the
3232
previous method, this call does not result in the copying of the image from flash storage into
3333
a python bytearray. The token can be passed instead. This may result in faster rendering of the
34-
splashscreen background.
34+
splash screen background.
3535

‎docs/library/datastore.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ two possible types:
2424

2525
- *Factory settings* or *Read-only memory (ROM)* storage. Manufacturers can
2626
provision the DL-7450 with application data in the manufacturing process,
27-
such as branded splashscreen backgrounds or the URL of a content provider.
27+
such as branded splash screen backgrounds or the URL of a content provider.
2828
It is also possible to provide unique-per-dock (UPD) data, such as
2929
enrolment tokens for IoT cloud service providers.
3030
- *Runtime settings:* Applications may store data that is not set in the
@@ -45,7 +45,7 @@ There is an additional non-persistent storage type:
4545

4646
When an application requests an item from the datastore, unless explicitly
4747
stated otherwise, there is an order of preference. For example if the
48-
application requests a splashscreen background with image tag *default_img*,
48+
application requests a splash screen background with image tag *default_img*,
4949
first the ephemeral store will be checked, followed by the runtime store and
5050
finally the ROM/factory store.
5151

@@ -65,7 +65,7 @@ images and key-value data.
6565
+--------------+----------------------------+
6666

6767

68-
.. admonition:: Not-yet implemented
68+
.. admonition:: Not yet implemented
6969
:class: tip
7070

7171
In the present version of the DL-7450 SDK only the application ROM store is

‎docs/library/dock.DockControl.rst‎

Lines changed: 109 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -6,91 +6,116 @@ class DockControl -- Manage dock settings
66

77
The DockControl class provides DL-7450 management services to applications.
88

9-
Constructors
10-
------------
11-
129
.. class:: DockControl()
1310

1411
Construct a DockControl object.
1512

16-
.. admonition:: Coming soon
17-
:class: tip
18-
19-
In later releases, the DockControl interface will give the application developer
20-
more control of the dock including:
21-
22-
- set the attached screens to different resolutions.
23-
- show different content on different attached monitors.
24-
- set WiFi credentials such as SSID and password.
25-
26-
Methods
27-
-------
28-
29-
.. method:: DockControl.set_timezone(tz)
30-
31-
Set the timezone of the DL-7450 device. The parameter is a string which can be any of
32-
the accepted abbreviations from the `Time Zone Database. <https://www.iana.org/time-zones>`_
33-
For example::
34-
35-
from dock import DockControl
36-
control = DockControl()
37-
control.set_timezone("PST8PDT")
38-
39-
If an attempt is made to set a timezone that does not exist a `ValueError` exception is raised.
40-
For an invalid type a `TypeError` is raised.
41-
42-
.. admonition:: Coming soon
43-
:class: tip
44-
45-
In this preview a limited subset of the IANA timezones are supported.
46-
47-
+----------------------+-----------------------------------------------------+
48-
| Zone Code | Notes |
49-
+======================+=====================================================+
50-
| CET | Central European Time |
51-
+----------------------+-----------------------------------------------------+
52-
| CST6CDT | USA Central Standard Time with daylight saving |
53-
+----------------------+-----------------------------------------------------+
54-
| EET | Eastern European Time with daylight saving |
55-
+----------------------+-----------------------------------------------------+
56-
| EST | Eastern Standard Time |
57-
+----------------------+-----------------------------------------------------+
58-
| GB | UK/Eire with daylight saving |
59-
+----------------------+-----------------------------------------------------+
60-
| GMT | UK/Eire standard time |
61-
+----------------------+-----------------------------------------------------+
62-
| HST | Hawaii–Aleutian time |
63-
+----------------------+-----------------------------------------------------+
64-
| Hongkong | |
65-
+----------------------+-----------------------------------------------------+
66-
| Israel | |
67-
+----------------------+-----------------------------------------------------+
68-
| Japan | |
69-
+----------------------+-----------------------------------------------------+
70-
| MET | Same as CET |
71-
+----------------------+-----------------------------------------------------+
72-
| MST | A zone that observes MST without daylight saving |
73-
| | such as Arizona |
74-
+----------------------+-----------------------------------------------------+
75-
| MST7MDT | Mountain Standard Time with daylight saving |
76-
+----------------------+-----------------------------------------------------+
77-
| NZ | |
78-
+----------------------+-----------------------------------------------------+
79-
| PRC | China |
80-
+----------------------+-----------------------------------------------------+
81-
| PST8PDT | Pacific Standard Time with daylight saving |
82-
+----------------------+-----------------------------------------------------+
83-
| ROC | Taipei |
84-
+----------------------+-----------------------------------------------------+
85-
| ROK | Republic of Korea |
86-
+----------------------+-----------------------------------------------------+
87-
| Singapore | |
88-
+----------------------+-----------------------------------------------------+
89-
| UCT | Universal Coordinated Time |
90-
+----------------------+-----------------------------------------------------+
91-
| UTC | Universal Coordinated Time |
92-
+----------------------+-----------------------------------------------------+
93-
| W-SU | Moscow |
94-
+----------------------+-----------------------------------------------------+
95-
| WET | West European Time |
96-
+----------------------+-----------------------------------------------------+
13+
.. admonition:: Coming soon
14+
:class: tip
15+
16+
In later releases, the DockControl interface will give the application developer
17+
more control of the dock including:
18+
19+
- set the attached screens to different resolutions.
20+
- show different content on different attached monitors.
21+
- set WiFi credentials such as SSID and password.
22+
23+
.. method:: DockControl.suspend_host_connection(suspend: bool) -> None
24+
25+
Send a signal to suspend/resume the host connection when a host device, such as
26+
a laptop or a desktop, is connected.
27+
28+
This allows the python application to take control of the splashscreen, display
29+
pixels, and revoke connection to the dock.
30+
31+
.. caution::
32+
Suspending the connection locks out the dock from access to both pixels and usb
33+
devices, effectively preventing its use as a dock.
34+
35+
The connection will be suspended until either a resume is sent, an
36+
unplug/plug cycle of the device happens, or power cycle of the dock.
37+
38+
.. caution::
39+
The delay between requesting the suspend/resume signal and the actual
40+
suspension/resumption of the host connection is currently quite long
41+
- several seconds. This will be addressed in a future release.
42+
43+
.. code-block:: python
44+
45+
from dock import DockControl
46+
47+
control = DockControl()
48+
control.suspend_host_connection(True) # Suspend host connection
49+
control.suspend_host_connection(False) # Resume host connection
50+
51+
.. method:: DockControl.set_timezone(timezone: str) -> None
52+
53+
Set the timezone of the DL-7450 device. The parameter is a string which can be any of
54+
the accepted abbreviations from the `Time Zone Database. <https://www.iana.org/time-zones>`_
55+
For example:
56+
57+
.. code-block:: python
58+
59+
from dock import DockControl
60+
61+
control = DockControl()
62+
control.set_timezone("PST8PDT")
63+
64+
If an attempt is made to set a timezone that does not exist a `ValueError` exception is raised.
65+
For an invalid type a `TypeError` is raised.
66+
67+
.. admonition:: Coming soon
68+
:class: tip
69+
70+
In this preview a limited subset of the IANA timezones are supported.
71+
72+
+----------------------+-----------------------------------------------------+
73+
| Zone Code | Notes |
74+
+======================+=====================================================+
75+
| CET | Central European Time |
76+
+----------------------+-----------------------------------------------------+
77+
| CST6CDT | USA Central Standard Time with daylight saving |
78+
+----------------------+-----------------------------------------------------+
79+
| EET | Eastern European Time with daylight saving |
80+
+----------------------+-----------------------------------------------------+
81+
| EST | Eastern Standard Time |
82+
+----------------------+-----------------------------------------------------+
83+
| GB | UK/Eire with daylight saving |
84+
+----------------------+-----------------------------------------------------+
85+
| GMT | UK/Eire standard time |
86+
+----------------------+-----------------------------------------------------+
87+
| HST | Hawaii–Aleutian time |
88+
+----------------------+-----------------------------------------------------+
89+
| Hongkong | |
90+
+----------------------+-----------------------------------------------------+
91+
| Israel | |
92+
+----------------------+-----------------------------------------------------+
93+
| Japan | |
94+
+----------------------+-----------------------------------------------------+
95+
| MET | Same as CET |
96+
+----------------------+-----------------------------------------------------+
97+
| MST | A zone that observes MST without daylight saving |
98+
| | such as Arizona |
99+
+----------------------+-----------------------------------------------------+
100+
| MST7MDT | Mountain Standard Time with daylight saving |
101+
+----------------------+-----------------------------------------------------+
102+
| NZ | |
103+
+----------------------+-----------------------------------------------------+
104+
| PRC | China |
105+
+----------------------+-----------------------------------------------------+
106+
| PST8PDT | Pacific Standard Time with daylight saving |
107+
+----------------------+-----------------------------------------------------+
108+
| ROC | Taipei |
109+
+----------------------+-----------------------------------------------------+
110+
| ROK | Republic of Korea |
111+
+----------------------+-----------------------------------------------------+
112+
| Singapore | |
113+
+----------------------+-----------------------------------------------------+
114+
| UCT | Universal Coordinated Time |
115+
+----------------------+-----------------------------------------------------+
116+
| UTC | Universal Coordinated Time |
117+
+----------------------+-----------------------------------------------------+
118+
| W-SU | Moscow |
119+
+----------------------+-----------------------------------------------------+
120+
| WET | West European Time |
121+
+----------------------+-----------------------------------------------------+

0 commit comments

Comments
 (0)