church-clocks

    1.3.1 • Public • Published

    Church Clocks

    A nodejs script which is designed to provide a websocket connection to gain information from ProPresenter, ProVideoPlayer, Elvanto, and Fluro

    Installation

    This module supports running a required script in your own code or can be run directly.

    • First install nodejs and npm on your machine
    • Type npm install -g church-clocks --unsafe_perm=true to install the module When installing the installer should ask if you want to set the settings for each module

    Using as a standalone webserver

    This module includes a standalone script which exposes a websocket and/or a webserver for accessing the clocks

    Running

    In order to run as a standalone webserver you must install the module above and run the installer script to configure the configuration files which will be at <userdirectory>/.church-clocks. This script will be ran when installing church-clocks or can be ran again by running generateSettings.js

    • Find the location where npm installed the module typically in /usr/local/lib/node or /usr/local/lib/node_modules for linux machines and %USERPROFILE%\AppData\Roaming\npm\node_modules for windows
    • Navigate to the .church-clocks directory cd /usr/local/lib/node_modules/church-clocks
    • Run node run.js to run it or node install.js to generate the settings file

    Running on boot (Linux)

    In order to run on boot you need to find the command that is required to run the module above. This will typically be in /usr/local/lib/node_modules/church-clocks

    • First install pm2 npm install pm2 -g
    • Type pm2 start /usr/local/lib/node_modules/church-clocks/pm2Service.json
    • Type pm2 save to save the changes
    • Type pm2 startup to make it launch on boot
    • Check the logs with pm2 logs church-clocks

    WebSocket

    Connecting

    The WebSocket can be at <YOUR_IP>:9955 and when connected should output all supported events which can be seen below in the API reference.

    Command format

    In general the command format can be seen in the API reference, however the WebSocket is formatted differently.

    Receiving from server

    The following is the format that is expected to come from the WebSocket to your script

    {
        "event": "The event that is being outputted",
        "value": "The value of that event
    }
    

    So as an example a supported function would come in as follows:

    {
        "event": "functionEvent",
        "value": {
            "function": "functionName",
            "command": "command",
            "value": "value"
        }
    }
    

    Sending to server

    The following is the format that is expected to be sent to the WebSocket from your script

    {
        "password": "if the password is required by the function",
        "function": "function name",
        "command": "the command to be processed,
        "value": "the value of tht command
    }
    

    So as an example setting the Elvanto service would be as follows:

    {
        "password": "password if set in the general settings file",
        "function": "elvanto",
        "command": "setService",
        "value": "The elvanto live url for the wanted service"
    }
    

    This commands can be found below in function commands

    WebServer

    This module also provides a web server that allows things like ProPresenter to use for it's stage display functionality

    How to use

    This server if enabled can be accessed at <host>:<configured port>/index.html?type=<type> and will display a webpage based on the passed parameter type By default the configured port is 80

    Supported Parameters

    • type The type of clock to be displayed
    • backgroundcolor The background color to be set if required (Note use * instead of # so #0C056D would be *0C056D)
    • color The text color to be set if required (Note use * instead of # so #0C056D would be *0C056D)
    • scale The scale of the page. Setting the scale parameter sets the font-size of all text
    • font The font to display

    For example http://localhost/?type=elvanto_countdown_clock&backgroundcolor=*4C146D&scale=20em&font=arial

    Supported types

    • current_time This will display the current system time
    • elvanto_countdown_clock This will display the elvanto countdown clock (Current time left for current item)
    • fluro_countdown_clock This will display the fluro countdown clock (Current time left for current item)
    • elvanto_items This will display the current item followed by the next item
    • elvanto_currentitem This will display the current item name
    • elvanto_nextitem This will display the next item name *pvp_video_clock This will display the video countdown clock for ProVideoPlayer. `pvp-transportid must be set to the id of the transport you wish to get the time from *pp_video_clock``` This will display a video countdown clock for ProPresenter.
    • pvpandpp_video_clock This will display a clock depending on ProPresenter or ProVideoPlayers clock. If the main clock is not active the other clock if active will display the value. Setting parameter main_clock=pvp/pp will set what clock takes importance with the pvp clock being default. pvp_transportid must be set to the id of the transport you wish to get the time from
    • pp_lyric_next This will display the next lyric in ProPresenter
    • pp_lyric_current This will display the current lyric in ProPresenter
    • debug Will show all the incoming data. Useful if you're developing your own solution

    Using as an included module

    • Include the module using const churchClocks = require("church-clocks");.
    • Then create the object using new churchClocks(webSocketEnabled, webSocketPassword, webSocketPort, webServerEnabled, webServerPort, filePath) Where webSocketEnabled will enable/disable the websocket, websocketPassword will set the password that is required to pass in the WebSocket password to perform commands, webSocketPort will change the port used to access the websocket, webServerEnabled will enable/disable the inbuilt webserver, filePath is where the settings files are stored default is %USERPROFILE%/.church-clocks/ for windows and ~/.church-clocks/ for linux.

    Events

    Events can be accessed by using object.on(<eventName>, function(){}) In general all functions will output information as events which can be seen below

    • connectionStatus is the emitter for updating on connection state changes
    {
        function: "the function name",
        state: "status"
    }
    
    • error is the emitter for errors
    {
        function: "the function name",
        errorType: "critical/warning",
        error: "The error"
    }
    
    • functionEvent events from the functions. This is usually where status comes from
    {
        "function": "the function name",
        "type": "the type of command being sent",
        "value": "the value"
    }
    
    • information information events
    {
        "function": "the function name",
        "type": "the type of command being sent",
        "value": "the value" 
    }
    

    Configuration

    The configuration files can be edited using the admin control panel found at admin.html the password is by default an empty string (just hit login without entering anything)

    The configuration files can be found at the location listed when running node run.js this should be in your user directory (for Windows C:/users/<user>/.church-clocks for Linux /home/<user>/.church-clocks)

    Application Settings

    In the .church-clocks directory there will be a file called applicationSettings.txt this is the settings for the application.

    • webSocketEnabled Should the websocket be enabled? Default true
    • webSocketPassword What should the password be for the websocket? This is also used in admin configuration pages. Default ""
    • webSocketPort Should the websocket be enabled? Default 9955. This will be forced to port 9955 if the web server is enabled!
    • webServerEnabled Should the web server be enabled? Default true
    • webServerPort What port should the web server be on? Default 80

    Function Settings

    In the .church-clocks\functionSettings directory there will be several files for each function below.

    Fluro settings

    The Fluro module is setup to dynamically grab the next service depending on the settings provided. This is for use with the Fluro live project (Coming soon)

    • enabled Should the function be enabled?
    • apiKey: An API Key from Fluro
    • realm: The ID of a realm the event(s) are stored in
    • track: The ID of an event track that the event(s) are stored in
    • date: Specify a date to get events for (useful for testing) // Should be in YYYY-MM-DD format
    • eventID: Specify a specific event ID (the first plan will be fetched)*
    • planID: Grab a specific plan
    • roomIDs: Used by the setFluroClock.html page to search for events. Can be separated by a ,.
    • timezone Change the timezone used. Default Melbourne/Australia
    • serviceChangeRedirectURL What URL should the setFluroClock.html page send the user to on successful plan update. <planId> will populate the plan id, <eventId> will populate the eventId that was chosen.

    Elvanto settings

    • enabled Should the function be enabled?
    • username Your Elvanto bot username
    • password Your Elvnato bot password
    • puppeteerExecutablePath Change the puppeteerExecutablePath if required

    ProPresenter settings

    • enabled Should the function be enabled?
    • host The host ip address
    • port The host port
    • password The password found in the settings

    ProVideoPlayer settings

    • enabled Should the function be enabled?
    • host The host ip address
    • api The api location. Default /api/0/
    • authToken The auth token found in settings

    Function Commands

    Below are commands that are supported to send to functions

    {
        "password": "if the password is required by the function",
        "function": "function name",
        "command": "the command to be processed,
        "value": "the value of tht command
    }
    

    Commands may also respond using the following sent directly to the current web socket connection

    {
        "event": "response",
        "value": {
            "function": "functionName",
            "command": "command",
            "value": "value"
        }
    }
    //Note if there is an error this will return false or a description of the error in the value
    

    Elvanto

    setService

    Will update the service

    {
        "password": "is required",
        "function": "elvanto"
        "command": "setService"
        "value": "?id=joijio6-hiuht-uhi6-hiuhiu65-hiuhiu5&time_id=wifuwehfiweiufh-hi7-hi65-iuhiuhiuhiu65"
    }
    

    clearService

    Will clear the current clock

    {
        "password": "is required",
        "function": "elvanto"
        "command": "clearService"
        "value": ""
    }
    

    Fluro

    getEvents

    Will get a list of events within the set configuration and a range of 3 days from the current date

    //Request
    {
        "password": "is required",
        "function": "fluro"
        "command": "getEvents"
        "value": ""
    }
    //Response
    {
        "event": "response",
        "value": {
            "function": "fluro",
            "command": "getEvents",
            "value": {
                "events": An array of events,
                "serviceChangeRedirectURL": The url set in the configuration file
            }
        }
    }
    

    clearClock

    Will clear the current clock. Note if you have set an event/plan etc in the settings it will return back to that

    //Request
    {
        "password": "is required",
        "function": "fluro"
        "command": "clearClock"
        "value": ""
    }
    //Response
    {
        "event": "response",
        "value": {
            "function": "fluro",
            "command": "clearClock",
            "value": true
        }
    }
    

    setEvent

    Will set an event

    //Request
    {
        "password": "is required",
        "function": "fluro"
        "command": "setEvent"
        "value": "<eventId>"
    }
    //Response
    {
        "event": "response",
        "value": {
            "function": "fluro",
            "command": "setEvent",
            "value": true
        }
    }
    

    setURL

    Will set an event

    //Request
    {
        "password": "is required",
        "function": "fluro"
        "command": "setURL"
        "value": "A fluro live URL (This is expected to use live.fluro.io)"
    }
    //Response
    {
        "event": "response",
        "value": {
            "function": "fluro",
            "command": "setURL",
            "value": true
        }
    }
    

    Troubleshooting

    Elvanto saying it cannot open the browser

    This is probably due to puppeteer. Try a few things below to see if it solves your issue

    • Try setting the last parameter in the elvanto settings file to /usr/bin/chromium-browser for linux machines
    • Try setting the last parameter in the elvanto settings file to the location of the chromium browser
    • Try installing chromimum

    Keywords

    none

    Install

    npm i church-clocks

    DownloadsWeekly Downloads

    33

    Version

    1.3.1

    License

    Apache-2.0

    Unpacked Size

    224 kB

    Total Files

    26

    Last publish

    Collaborators

    • haydendonald