Event Sources

Introduction

Dashboard gets data from backend by using event sources registered in 'config.js' file. Event sources registry is array contains objects with Event Sources definitions. Each object contains at least three mandatory fields:

type (String) – Event Source type. Allowed values are: "WSS", "SSE", "FETCH", "FILE"
url (String) – Event Source URL
events (Array) – white list of emitted events names (other events will be ignored)

Each Event Source depends of used protocol can emit formatted or unformatted data. Server-sent Events (SSE) and File (FILE) event sources can contain field with event name, WebSocket (WSS) and Fetch (FETCH) can contain only raw data.

WSS
WebSocket Event Source (push)

WSS (WebSocket) event source can be used in case we want push data from server to dashboard. WSS (WebSocket) provide full-duplex communication channels over a single TCP connection, but dashboard use just server to client direction.

Definition in 'config.js' file:

type (String) – "WSS"
url (String) – valid WebScocket Server URL (starts from "ws://" or "wss://")
events (Array) – array of single entry with event name

Example:

sys_eventProviders = [
    ...
    {
        type:   "WSS",                           // WebSocket event provider
        url :   "wss://ws.weather.myserver.com", // WebSocket server URL
        events: ["temperature"]                  // Event name
    },
    ...
];

Data format:

Unformatted raw character or binary data.
Please see: WebSockets Living Standard for more information.

Example:

HELLO NĖURO!

Example: ws.py – Simple python3 script to send data through WebSocket

#!/usr/bin/python3

import time
import random
import asyncio
import websockets

async def send(websocket, path):

    # Send the message
    while True:
        await websocket.send(str(random.randrange(10, 99)))
        time.sleep(3)

try:
    HOST = 'localhost'
    PORT = 8082

    server = websockets.serve(send, HOST, PORT)
    print('Server started.\nURL: ws://' + HOST + ':' + str(PORT))
    asyncio.get_event_loop().run_until_complete(server)
    asyncio.get_event_loop().run_forever()

except KeyboardInterrupt:
    asyncio.get_event_loop().stop()
    print('\nServer ended.')

SSE
Server-sent Events Event Source (push)

SSE (Server-sent Events) event source can be used in case we want push data from server to dashboard. Unlike WebSockets, Server-sent Events are a one way communications channel - events flow from server to client only.

Definition in 'config.js' file:

type (String) – "SSE"
url (String) – valid HTTP Server URL (starts from "http://" or "https://")
events (Array) – array of event names

Example:

sys_eventProviders = [
    ...
    {
        type:   "SSE",                             // Server-sent Events provider
        url :   "http://sse.weather.myserver.com", // HTTP server URL
        events: ["temperature", "humidity"]        // Event names
    },
    ...
];

Data format:

Character data in standard Server-sent Events format.
Please see: Server-sent Events Living Standard for more information.

Example:

event: usermessage
data: HELLO NĖURO!

Example: sse.py – Simple python3 script to send data through Server-sent Events

#!/usr/bin/python3

import time
import random
from http.server import BaseHTTPRequestHandler,HTTPServer

# HTTP request handler
class myHandler(BaseHTTPRequestHandler):

    # Handle GET method
    def do_GET(self):
        self.send_response(200)
        self.send_header('Access-Control-Allow-Origin', '*')
        self.send_header('Content-Type', 'text/event-stream')
        self.send_header('Cache-Control', 'no-cache')
        self.send_header('Connection', 'keep-alive')
        self.end_headers()

        # Send the message
        while True:
            self.wfile.write(bytes('event: temperature_sse\n','utf-8'))
            self.wfile.write(bytes('data: ' + str(random.randrange(10, 99)) + '\n\n','utf-8'))
            time.sleep(3)

try:
    HOST = 'localhost'
    PORT = 8081

    server = HTTPServer((HOST, PORT), myHandler)
    print('Server started.\nURL: http://' + HOST + ':' + str(PORT))
    server.serve_forever()

except KeyboardInterrupt:
    server.socket.close()
    print('\nServer ended.')

FETCH
Fetch Event Source (pull)

FETCH (Fetch) event source can be used in case we want pull data from server to dashboard. Unlike WebSockets and Server-sent Events Fetch pull data from server to client.

Definition in 'config.js' file:

type (String) – "FETCH"
url (String) – valid HTTP Server URL (starts from "http://" or "https://")
events (Array) – array of single entry with event name
interval (Number) – fetch interval in milliseconds
method (String) – HTTP request method. Default: "GET"
body (String, body types) – HTTP request body
headers (Object, Headers) – Default: {}
credentials (String) – Authentication credentials mode. Default: "omit"
- "omit" – don't include authentication credentials (e.g. cookies) in the request
- "same-origin" – include credentials in requests to the same site
- "include" – include credentials in requests to all sites

Example:

sys_eventProviders = [
    ...
    {
        type:   "FETCH",                           // Fetch provider
        url :   "http://api.weather.myserver.com", // HTTP server URL
        events: ["temperature"],                   // Event name
        interval: 5000                             // pull interval (5 seconds)
    },
    ...
];

Data format:

Unformatted character or binary data.
Please see: Fetch Living Standard for more information.

Example:

HELLO NĖURO!

Example: fetch.py – Simple python3 script to serve data for the Fetch API

#!/usr/bin/python3

import random
from http.server import BaseHTTPRequestHandler,HTTPServer

# HTTP request handler
class myHandler(BaseHTTPRequestHandler):

    # Handle GET method
    def do_GET(self):
        self.send_response(200)
        self.send_header('Access-Control-Allow-Origin', '*')
        self.send_header('Content-Type', 'text/plain')
        self.send_header('Cache-Control', 'no-cache')
        self.end_headers()

        # Send the message
        self.wfile.write(bytes(str(random.randrange(10, 99)),'utf-8'))

try:
    HOST = 'localhost'
    PORT = 8080

    server = HTTPServer((HOST, PORT), myHandler)
    print('Server started.\nURL: http://' + HOST + ':' + str(PORT))
    server.serve_forever()

except KeyboardInterrupt:
    server.socket.close()
    print('\nServer ended.')

FILE
File Event Source (pull)

FILE (File) event source can be used in case we want pull data from server or local file to dashboard. Unlike WebSockets and Server-sent Events File event source allow pull data from server to client. Unlike FETCH event source FILE event source allow to pull data from local files by using file:// protocol).

Definition in 'config.js' file:

type (String) – "FILE"
url (String) – valid JavaScript file URL (starts from "file://") or relative path or absolute path (starts from "/")
events (Array) – array of event names
interval (Number) – fetch interval in milliseconds

Example:

sys_eventProviders = [
    ...
    {
        type:   "FILE",                      // File provider
        url :   "my-event-provider.js",      // JavaScript data provider
        events: ["temperature", "humidity"], // Event names
        interval: 5000                       // pull interval (5 seconds)
    },
    ...
];

Data format:

JavaScript wrapped data with two mandatory fields: "event" and "data"

Example:

event="usermessage"
data="HELLO NĖURO!"

Example: file.py – Simple python3 script to provide data for local file read

#!/usr/bin/python3

import time
import random
import os
import tempfile

file = os.path.join(tempfile.gettempdir(), "data.tmp")
f = open(file, 'w')
print('Start writing to file.\nURL: file://' + f.name)

try:
    while True:
        # Write the message
        f.seek(0)
        f.write('event="temperature_file";data=' + str(random.randrange(10, 99)))
        time.sleep(3)

except KeyboardInterrupt:
    f.close()
    print('\nFile closed.')

Event Sources

Introduction

WSS WebSocket Event Source (push)

SSE Server-sent Events Event Source (push)

FETCH Fetch Event Source (pull)

FILE File Event Source (pull)

WSS
WebSocket Event Source (push)

SSE
Server-sent Events Event Source (push)

FETCH
Fetch Event Source (pull)

FILE
File Event Source (pull)