# Mark 1 Display

## About **Enclosures**

The Mark 1 **Device** is housed in an **Enclosure**. An Enclosure is a shell that houses a **Device** that runs Mycroft. In the future, different **Enclosures** will have different capabilities.

## The Mark 1 Enclosure capabilities

The Mark 1 *mouth* and *eyes* can be controlled by **Skills** using the `self.enclosure` object inherited from the `MycroftSkill` base class. This object acts as an interface to the **Enclosure** and allows the Skill creator to draw to the *mouth* display.

This is how the *mouth* and *eyes* are made to change during operations such as audio playback.

### Drawing to the *mouth* display

#### Drawing text to the *mouth* display

Text can be sent to the display using the `mouth_text()` method of the `enclosure` object.

```python
        self.enclosure.mouth_text('The meaning of life, the universe and everything is 42')
```

If the text is too long to fit on the display, the text will scroll.

@TODO how many characters will fit on the display before it will scroll?

#### Drawing images to the *mouth* display

**Clearing an existing image from the mouth display**

Before writing an image to the *mouth* display, you should clear any previous image.

```python
        self.enclosure.mouth_display(img_code="HIAAAAAAAAAAAAAA", refresh=False)
        self.enclosure.mouth_display(img_code="HIAAAAAAAAAAAAAA", x=24, refresh=False)
```

*Copied from the skill-date-time*

#### How images are drawn on the *mouth* display

The *mouth* display is a grid, 32 pixels wide and 8 pixels high.

There are two ways to draw an image on the *mouth* display.

**Addressing each pixel using a string encoding**

You can draw an image to the *mouth* display by binary encoding pixel information in a string.

The binary encoding is straightforward value substitution.

| Letter Value | Pixel value |
| ------------ | ----------- |
| A            | 0           |
| B            | 1           |
| C            | 2           |
| D            | 3           |
| E            | 4           |
| F            | 5           |
| G            | 6           |
| H            | 7           |
| I            | 8           |

and so on.

```python
        self.enclosure.mouth_display(img_code="HIAAAAAAAAAAAAAA", refresh=False)
        self.enclosure.mouth_display(img_code="HIAAAAAAAAAAAAAA", x=24, refresh=False)
```

The code above clears the image by sending a string consisting of `HI` which stands for a Width of 7 and a height of 8 and each A stands for a segment of 4 pixels in the off state.

@TODO I kinda get this, but I think we really need a grid image here to show how it works - to make it easier to understand.

**Sending a PNG image to the mouth display**

Another way to draw an image on the *mouth* display is to create a PNG-formatted image with a width of 32 pixels and a height of 8 pixels, then use the `mouth_display_png()` method of the `enclosure` object.

The image should be black and white, with white meaning a dark pixel, and black indicating an illuminated pixel.

`mouth_display_png()` expects the first argument to be the image absolute path. Optional arguments are

* `threshold`: The value at which a pixel should be considered 'dark' or 'illuminated'
* `invert`: Treat white in the image as illuminated pixels, and black as dark pixels
* `x`: The x position (horizontal) at which the image should be displaye, in pixels
* `y`: The y position (vertical) at which the image should be displayed, in pixels
* `refresh`: clear the display before writing to it

@TODO all the above needs to be validated - the information is educated guesswork

```python
        self.mouth_display_png('/path/to/image.png', threshold=70, invert=False, x=0, y=0, refresh=True)
```

Example image: ![A note symbol](https://akeiexil.files.wordpress.com/2017/08/note1.png)

**Tools for converting PNG image representations to string representations**

If you don't want to convert PNG files at runtime (for example when creating simple animations) [this short python script](https://gist.github.com/forslund/9d8805fd7adb9e74ec3ea321e1676a21) will convert PNG files to strings compatible with the `img_code` of `self.enclosure.mouth_display()`.

#### Resetting the display to the default state

When the **Skill** is finished, you should reset the **Enclosure** to the default state using

```python
        self.enclosure.reset()
```

This will clear the screen and blink the Mark 1's *eyes* once.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mycroft-ai.gitbook.io/docs/skill-development/displaying-information/mark-1-display.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.