Character Displays

Character displays are useful for providing a visual feedback of the status of MudPi. Displays are typically 16x2 or 20x4 sizes and allow you to write text output to a screen.

Display Basics

The display is a component that extends from the base CharDisplay class. Displays will have a message queue of messages to display and cycle through them each for a set duration.

Message Queue

Each display will have its own message queue. The message queue will contain messages along with a duration for how long to display each message. The duration is in seconds. Messages get added to the queue through events sent to the display via its configured topic. The message queue has a limit set through message_limit in the configuration. Once the limit is reached, the oldest message in the queue will be discarded without display when a new message is added to the queue.

Available Interfaces

Below is a list of currently supported interfaces for character displays.

If you would like at add support for another character display interface read the developer docs and submit a PR!

Available Actions

In order to interact with a character display you need to use the actions it provides (typically on a trigger). You can also interact with displays over the event system which in turn stil calls the actions provided. You can use the following actions on displays:

Controlling Displays Through Events

Below are the events that a display is also listening for and how you can interact with displays by sending an event to it.

topic: Based on value set for topic option in display configuration. Default: char_display/{key}

Add Message to the Queue

Send a Message event to add a message to the display's queue. The display will expect that you send a message and duration in the data of the event. You can use the newline \n to advance text to the next line.

{
    "event": "Message",
    "data": {
    	"message": "Text Top Row\nSecond Row",
    	"duration": 5
	}
}

Clear the Display

If you wish to clear the screen of the display immediately you can send a Clear event. There is no other data required in the event.

{
    "event": "Clear",
    "data": 0
}

Clear the Message Queue

To clear the entire message queue you can send a ClearQueue event to the display. No other event data is required.

{
    "event": "ClearQueue",
    "data": 0
}

Dynamic Messages

Sometimes when sending a message to a display you may want to include some dynamic data from the system such as a sensor reading. MudPi has short code replacements for display messages that allows you to dynamically look up values stored in the state manager for display.

An example of a dynamic message is that you may want to display a message such as "Temperature: 70". However you would not want to hard code the text "70". Instead you would want this to be the actual temperature from your connected sensor.

When you attach a component to MudPi often a value is stored in the state manager for the component based on the key that you set. We can use this key in our message to dynamically look up the value that is stored under it. To tell MudPi to look up a state, put the key you want fetched between square brackets.

Here is an example of an event that would display our example message "Temperature: 70" but instead look up that actual value and replace it for us. This event assumes we have a temperature sensor connected to MudPi with a key of dht.

{
    "event": "Message",
    "data": {
    	"message": "Temperature: [dht.temperature]",
    	"duration": 5
	}
}

The event above would tell MudPi to go look up a state key of dht and replace this text with the result. Any value put between sqaure brackets will be treated as a redis key to fetch data for. If no result is found the text would be empty.

In the example above the dht device stores data as a dict. In order to get nested data from a dict we use a period followed by the key of the dict we want. So if our system contained a dict for the dht device it would attempt to look for a key of temperature in that dict. For example if this value found was 68 for the key dht.temperature, then our display would output a message on the screen of "Temperature: 68".

Add Message to the Front of Queue

Sometimes you may want to send a message to a specific position in the queue like the front. This way you can display an important message without needing to clear the display. Send a Message event to add a message to the display's queue. The display will expect that you send a message and duration and the optional position to instruct the display to insert the message a specific spot in the queue rather than the end. The queue is 0 based index so setting the position to 0 means we want the message at the front of the queue.

{
    "event": "Message",
    "data": {
        "message": "Text Top Row\nSecond Row",
        "duration": 5,
        "position": 0
    }
}

Note: If you provide a position larger than the queue size it may cause errors. You can however provide a negative value which means X number of spots from the end.