You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
539 lines
32 KiB
539 lines
32 KiB
Mono Display File Format Specification
|
|
######################################
|
|
|
|
Generic Considerations
|
|
======================
|
|
|
|
Fundamental Unit
|
|
----------------
|
|
|
|
The fundamental data unit of a file in this format is an octet, i.e. 8 bits.
|
|
|
|
Endianness
|
|
----------
|
|
|
|
All numbers larger than a single octet are stored in **little endian** format.
|
|
|
|
Pixel Data
|
|
----------
|
|
|
|
Pixel data is always stored as raw 2D mono (1-bit) pixel images in the following manner:
|
|
|
|
- The raw 2D stream has the size ``(width_i * height_i + 8 - 1) / 8`` octets, where ``width_i`` is the width of the image, ``height_i`` the height of the image, and ``/`` is the standard integer division that always rounds down. (In Python 3 this would be the ``//`` operator.) This rounds the size of the raw 2D stream to a full octet. The excess pixels SHOULD be set to ``0`` by software writing this format, but MUST be ignored by software reading this format.
|
|
- We define a pixel index ``px_i = y_i * width_i + x_i``, where ``x_i`` is the x position of the pixel in the image, ``y_i`` the y position within the image, and ``width_i`` the width of the image.
|
|
- Each pixel index ``px_i`` can be decomposed into an octed index, ``px_i_o``, and a bit index ``px_i_b``, which are given by the formulas ``px_i_o = px_i / 8`` and ``px_i_b = px_i % 8``, where ``/`` and ``%`` are the integer division and modulo, respectively. A bit index of ``0`` indicates the least significant bit, and a bit index of ``7`` the most significant bit in the octet.
|
|
- Accessing the value of a pixel index can be done via ``value = (data_i[px_i_o] >> px_i_b) & 0x01``, where ``data_i`` is the array of octets containing the 2D data.
|
|
- If more than one 2D image is stored consecutively (for example for an animation) each 2D image will always start at an octet boundary. Hence while a new line within an image might not start at the boundary of an octet, images are always aligned to entire octets.
|
|
|
|
Draw Area
|
|
---------
|
|
|
|
The area that is drawn to is defined by the device and is irrespective of the data in this file. If the image data in the file exceeds the dimensions of the draw area of the device then the images will be clipped when drawn (but this is not considered to be an error).
|
|
|
|
Text
|
|
----
|
|
|
|
Text is stored as UTF-8 strings with preceding length information in some manner.
|
|
|
|
Alignment
|
|
---------
|
|
|
|
All sections and elements are aligned to 32 bits. In doubt padding bytes with values ``0`` MUST be inserted.
|
|
|
|
Fonts
|
|
-----
|
|
|
|
All fonts must be in the U8G2 font format that can be parsed by the u8g2-fonts Rust crate, see
|
|
<https://github.com/Finomnis/u8g2-fonts/> for details.
|
|
|
|
File Header
|
|
===========
|
|
|
|
The file header of a mono display file looks like the following:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Magic 0xAF | Magic 0x7E | Magic 0x2B | Magic 0x63 |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Version |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Number of Sections | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
Magic
|
|
-----
|
|
|
|
The file magic is the sequence of bytes ``0xAF 0x7E 0x2B 0x63``.
|
|
|
|
File Version
|
|
------------
|
|
|
|
This field indicates the version of the file. This allows a reader to determine if it supports the specific file. Any reader that supports a specific version MUST implement all mandatory features of that version.
|
|
|
|
The following possible values for the version field exist:
|
|
|
|
+-----------+--------------------------------------------+
|
|
| Value | Description |
|
|
+===========+============================================+
|
|
| ``0`` | Illegal |
|
|
+-----------+--------------------------------------------+
|
|
| ``1`` | A previous version of this specification. |
|
|
+-----------+--------------------------------------------+
|
|
| ``2`` | The current version of this specification. |
|
|
+-----------+--------------------------------------------+
|
|
| ``3`` .. | Reserved for future use |
|
|
+-----------+--------------------------------------------+
|
|
|
|
A value of ``0`` is illegal for the version field and indivates a problem with the file. The current specification version is ``1``. Writers that conform to this specification **MUST** use this value.
|
|
|
|
Number of Sections
|
|
------------------
|
|
|
|
This field indicates how many sections are present in this file. A value of ``0`` is valid, but indicates the file is empty.
|
|
|
|
Reserved
|
|
--------
|
|
|
|
This field is reserved for future use. Writers MUST set this field to ``0``.
|
|
|
|
Sections
|
|
========
|
|
|
|
A section consists of a section header, followed by the data of the section. The section header has the following structure:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Section Type | Size of the Section |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
Section Type
|
|
------------
|
|
|
|
The section type specifies what kind of section this is. The following section types are defined:
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Value | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Illegal |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` | List of drawn elements (always) |
|
|
+-----------+---------------------------------------------------+
|
|
| ``2`` | List of drawn elements (timespan) |
|
|
+-----------+---------------------------------------------------+
|
|
| ``3`` | List of drawn elements (list of timespans) |
|
|
+-----------+---------------------------------------------------+
|
|
| ``4`` .. | Reserved for future use |
|
|
| ``30`` | |
|
|
+-----------+---------------------------------------------------+
|
|
| ``31`` | Expiry Date |
|
|
+-----------+---------------------------------------------------+
|
|
| ``32`` | Custom Font |
|
|
+-----------+---------------------------------------------------+
|
|
| ``33`` .. | Reserved for future use |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
See below for the individual sections.
|
|
|
|
Size of the Section
|
|
-------------------
|
|
|
|
This 24bit value indicates the number of octets that contains the size of the section (including the 4 octets of the section header). This allows reader implementations to easily skip sections to iterate over the entire file.
|
|
|
|
List of drawn elements (always)
|
|
-------------------------------
|
|
|
|
This section contains a list of elements that are to be drawn. The section contains the following additional header:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Flags | Number of Elements |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
Flags
|
|
`````
|
|
|
|
The following flags are currently valid (bit ``0` is the least significant bit):
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Draw on the front side |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` | Draw on the back side |
|
|
+-----------+---------------------------------------------------+
|
|
| ``2`` | Clear the image buffer(s) before drawing |
|
|
+-----------+---------------------------------------------------+
|
|
| ``3`` .. | Reserved for future use |
|
|
| ``15`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
If neither the bits ``0`` or ``1`` are set the section will have no effect and will be ignored. If the bit ``2`` is set, any image buffer the elements of this section will be drawn to will be cleared (set to ``0``). For example, if both bits ``0`` and ``2`` are set (i.e. the flags have the value ``0x0005``), only the front side will be cleared before the image is drawn, while the back side will not be touched.
|
|
|
|
Writers MUST set reserved flags to zero.
|
|
|
|
Number of Elements
|
|
``````````````````
|
|
|
|
This contains the number of elements to be drawn in the section. A value of ``0`` is valid - in combination with the clear flag this allows a section to simply clear buffer without doing anything else.
|
|
|
|
List of drawn elements (timespan)
|
|
---------------------------------
|
|
|
|
This section is similar to the "List of drawn elements (always)" section, but the header contains two additional fields:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Flags | Number of Elements |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Start Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Start Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
12 | End Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
16 | End Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
The additional fields are two 64bit POSIX timestamps containing the start and end time during which this section is to be drawn. If the current timestamp is larger than or equal to the start timestamp, and the current timestamp is smaller than the end timestamp, the section will be shown, otherwise it will be skipped.
|
|
|
|
List of drawn elements (list of timespans)
|
|
------------------------------------------
|
|
|
|
This section is similar to the "List of drawn elements (timespan)" section, but the header contains a list of timestamp ranges, not just a single range:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Flags | Number of Elements |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Number of Timestamps | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | First Start Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
12 | First Start Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
16 | First End Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
20 | First End Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
24 | Second Start Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
28 | Second Start Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
32 | Second End Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
36 | Second End Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
40.. | Additional timestamps .... |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
After the last timestamp the list of elements follows (as with the "List of drawn elements (always)" and "List of drawn elements (timespan)" elements).
|
|
|
|
File Global Expiry Date
|
|
-----------------------
|
|
|
|
If this section is present it contains the timestamp that describes the date after which the file is no longer valid. This allows the user to generate
|
|
files that will be discarded if the current date is already past the expiry timestamp, and will automatically stop the file from being displayed
|
|
once the expiry timestamp is reached.
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Expiry Date Timestamp (Low) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Expiry Date Timestamp (High) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
Custom Font
|
|
-----------
|
|
|
|
This section defines a custom font that is to be used within this file. Any custom font used by draw elements MUST occur in the file before the font is used.
|
|
|
|
The section consists of the following type-specific header:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Actual Size of Font (octets) | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
This is followed by the font data itself in the format. The actual size indicates how long the font actually is in octets, which may be smaller than the padded length of the section indicates.
|
|
|
|
Elements
|
|
========
|
|
|
|
Each element is defined by an element header that contains the type of the element.
|
|
|
|
2D Image
|
|
--------
|
|
|
|
This contains a 2D image that is to be drawn at a specific position:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 1 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Reserved |
|
|
+------------------------+------------------------+-------------------------------------------------+
|
|
|
|
After the header the 2D image data follows immediately.
|
|
|
|
Animation
|
|
---------
|
|
|
|
This contains a sequence of 2D images of which one will be drawn at a specific position:
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 2 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Number of Frames |
|
|
+------------------------+------------------------+-------------------------------------------------+
|
|
12 | Update Interval | Reserved |
|
|
+-------------------------------------------------+-------------------------------------------------+
|
|
|
|
This is followed by ``N`` 2D images (where ``N`` is the number of frames specified). A value of ``0`` is not allowed for the number of frames.
|
|
|
|
The update interval is an unsigned 16bit integer that indicates the update interval. A value of ``0`` indicates the animation will be updated every tick, a value of ``1`` every second tick, etc., and a value of ``65535`` every 65536th tick (~ every 43 minutes).
|
|
|
|
Horizontal Scroll
|
|
-----------------
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 3 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Content Width |
|
|
+------------------------+------------------------+-------------------------------------------------+
|
|
12 | Flags | Scroll Speed (SS) | Reserved |
|
|
+-------------------------------------------------+-------------------------------------------------+
|
|
|
|
Flags
|
|
`````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Endless |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` | Invert Direction |
|
|
+-----------+---------------------------------------------------+
|
|
| ``2`` | Pad Left |
|
|
+-----------+---------------------------------------------------+
|
|
| ``3`` | Pad Right |
|
|
+-----------+---------------------------------------------------+
|
|
| ``4`` .. | Reserved for future use |
|
|
| ``7`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Scroll Speed
|
|
````````````
|
|
|
|
Every tick move by ``(SS + 1) / 16`` pixels.
|
|
|
|
Vertical Scroll
|
|
---------------
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 4 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Content Height |
|
|
+------------------------+------------------------+-------------------------------------------------+
|
|
12 | Flags | Scroll Speed (SS) | Reserved |
|
|
+-------------------------------------------------+-------------------------------------------------+
|
|
|
|
Flags
|
|
`````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Endless |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` | Invert Direction |
|
|
+-----------+---------------------------------------------------+
|
|
| ``2`` | Pad Top |
|
|
+-----------+---------------------------------------------------+
|
|
| ``3`` | Pad Bottom |
|
|
+-----------+---------------------------------------------------+
|
|
| ``4`` .. | Reserved for future use |
|
|
| ``7`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Scroll Speed
|
|
````````````
|
|
|
|
Every tick move by ``(SS + 1) / 16`` pixels.
|
|
|
|
Line
|
|
----
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 5 | X Origin |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Origin | X Target |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Y Target | Line Style | Flags |
|
|
+------------------------+------------------------+-------------------------------------------------+
|
|
|
|
Line Style
|
|
``````````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Solid line |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` .. | Reserved for future use |
|
|
| ``255`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Flags
|
|
`````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Line color is dark, not white |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` .. | Reserved for future use |
|
|
| ``7`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Box
|
|
---
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 6 | X |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Fill Pattern | Flags |
|
|
+------------------------+------------------------+-------------------------------------------------+
|
|
|
|
Fill Pattern
|
|
````````````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Solid |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` .. | Reserved for future use |
|
|
| ``255`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Flags
|
|
`````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Fill color is dark, not white |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` .. | Reserved for future use |
|
|
| ``7`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Clipped Text
|
|
------------
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 16 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Text Flags | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
12 | Font Index | Text Length |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
16.. | Text ... | Padding (if required) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
Text Flags
|
|
``````````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | Text is dark, background is white |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` .. | Reserved for future use |
|
|
| ``7`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
Font Index
|
|
``````````
|
|
|
|
0 .. 32767 built-in font (may not exist)
|
|
0x8000 + custom font in file (index - 0x8000 is the number within the file)
|
|
0x8000 is the first custom font in file
|
|
0x8001 the second
|
|
etc.
|
|
|
|
Horizontally Scrolling Text
|
|
---------------------------
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 17 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Text Flags | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
12 | Flags | Scroll Speed | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
16 | Font Index | Text Length |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
20.. | ... Text | Padding (if required) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
Current Time
|
|
------------
|
|
|
|
0 1 2 3
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
0 | Type: 32 | X Offset |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
4 | Y Offset | Width |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
8 | Height | Text Flags | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
12 | Font Index | UTC Offset (Minutes) |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
16 | Flags | Reserved |
|
|
+------------------------+------------------------+------------------------+------------------------+
|
|
|
|
UTC Offset
|
|
``````````
|
|
|
|
- signed 16 bit integer in minutes
|
|
|
|
Flags
|
|
`````
|
|
|
|
+-----------+---------------------------------------------------+
|
|
| Bit | Description |
|
|
+===========+===================================================+
|
|
| ``0`` | 12h clock (instead of 24h clock) |
|
|
+-----------+---------------------------------------------------+
|
|
| ``1`` | Show hours |
|
|
+-----------+---------------------------------------------------+
|
|
| ``2`` | Show minutes |
|
|
+-----------+---------------------------------------------------+
|
|
| ``3`` | Show seconds |
|
|
+-----------+---------------------------------------------------+
|
|
| ``4`` .. | Reserved for future use |
|
|
| ``15`` | |
|
|
+-----------+---------------------------------------------------+
|
|
|
|
|