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. You can read the display configuration docs for details on the required settings.

Display Basics

The display will be run by a display worker that listens for commands on when to display messages on the screen. This is done through the event system and there are a few events you can send to interact with displays through MudPi.

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.

Controlling Displays Through Events

Below are the events that a display is 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

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 redis 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 redis 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 value in redis, 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 redis key of dht_temperature and replace this text with the result. If no result is found the text would be empty. So if our system contained a value of 68 for the key dht_temperature, then our display would output a message on the screen of "Temperature: 68".

Testing Displays

Included with MudPi is an lcd_message_tool.py script for you to test displays with in the tools folder. Run the script and send events on a specified topic to test your displays are configured correctly. You can also interact with your displays using the MudPi UI that is installed through the installer.