Basic Display Stream Example

Use WebSockets to send data for display on an LED Matrix.

API Features Demonstrated

Platforms

This app works on:

Requirements and Prerequisites

Requires a ZentriOS evaluation board and an Adafruit 8x8 LED Matrix, such as provided with the Zentri ASG001 Monitor Backpack.

This app assumes your ZentriOS device is set up with the credentials to join your local network.

Resources

The file settings.ini is packaged with the zap and downloaded to the device.

The script websocket_client.py must be run on a computer connected to the same network as the device.

The script is in the ZentriOS_SDK project folder: ZentriOS_SDK/apps/basic/display_stream/websocket_client.py

Description

This app demonstrates how to send and receive data via WebSockets to a ZentriOS device. The python script websocket_client.py, connects to the ZentriOS web server and sends a single frame of data. The frame is written to the LED Matrix frame buffer. It appears as a diagonal line on the LED Matrix display.

The python script reads back the data from the frame and displays it as output.

Usage Instructions

The websocket_client.py python script requires the Python 2.7 websocket-client module. This is not part of the standard installation and may have to be installed. To install, you can use the command line:

pip install websocket-client

Open a ZentriOS serial terminal to the device. See Getting Started, Opening a ZentriOS Terminal.

This app assumes your ZentriOS device is set up with the credentials to join your local network. If you have not already set up network credentials, on the ZentriOS terminal, run the commands:

network_up -s
save

See the Wi-Fi Command API documentation for network_up and save.

After building, downloading and running the app to the ZentriOS device, the app displays on the ZentriOS terminal:

> Registering stream callbacks
Toggling network to start servers
Display stream app running...
Available routes:
  ws://display_stream.local/zapstreams/frame
  ws://display_stream.local/zapstreams/flush

Run the script websocket_client.py on a computer connected to the same network as the ZentriOS device. The script can be found in the ZentriOS_SDK project apps folder: ZentriOS_SDK/apps/basic/display_stream/websocket_client.py

The app displays a message similar to the following on the ZentriOS terminal:

[2015-11-24 | 03:46:35: Opened: 0]
disconnecting: 0
[2015-11-24 | 03:46:38: Closed: 0]
> disconnected: 0

The LED Matrix display shows a diagonal line determined by the data sent from the python script.

The python script outputs the frame value it reads back from the ZentriOS device:

Received '{u'data': u'[128,64,32,16,8,4,2,1]', u'stream': u'frame'}'

WebSocket Streams and Data Exchange

The app provides two WebSocket streams that are served by the ZentriOS webserver.

Data exchange between the client and server is based on a simple protocol in JSON format. The protocol is implemented by callbacks determined by the name of the WebSocket stream on which the message is sent.

Data Exchange Protocol

{
  'stream' : <stream name>,
  'method' : <method name>,
  'data'   : <data array>
}

where:

The settings.ini configures the ZentriOS Web Server with a CORS setting allowing resource access from external clients. CORS is required since the Python websocket client is not served by the ZentriOS (origin) device. The ZentriOS network discovery (mDNS) service is also configured to enable the Python websocket client to find the device on the network using a network name (rather than an IP address).

See the following links for additional information about the ZentriOS services used in this app.

Implementation

zn_app_init

frame_stream_callback

flush_stream_callback

Source

See:

See also: