Instructions for Linux



  • Monocle Gateway for Linux


    Requirements & Prerequisites

    Operating System & Hardware

    The Monocle Gateway application/service is supported on

    • Linux (x86)
    • Linux (x64)
    • Linux (ARMv7 32 bit) [Raspberry Pi 3B/3B+]
    • Linux (ARMv8 64 bit)

    Networking

    You computer should have a fix IP address on your local network. It may be a statically assigned IP address or a dynamically assigned fixed IP address. The IP cameras on your local network must be able to access this computer. A fixed address is needed because a DNS record is dynamically created for this host and the DNS record is what is provided to the Alexa devices to communicate with the Monocle Gateway.

    No other service or application can be serving on port 443. Amazon requires that cameras only connect to port 443 using secure TLS encrypted communications. If you have a firewall enabled on this computer, you must allow access to port 443 from other computers on your local private network. This ports does not need to be exposed to the Internet through your router.

    Additionally, ports 8554 & 8555 must be available and are used internally by the service on the computer. These ports do not need to be exposed thru the local firewall. These ports do not need to be exposed to the Internet through your router.

    This computer should be physically plugged into the network with a hard-wired ethernet connection. Wireless connections will technically work, but are less reliable and may provide less bandwidth and additional latency.


    Installation Instructions

    Please follow the instructions below to install and setup your Monocle Gateway service.

    1.) Create a temporary directory on your system to download the Monocle Gateway package.

    $ mkdir temp
    $ cd temp
    

    2.) Download the latest Monocle Gateway release build for your platform.

    Download the latest Monocle Gateway build for Linux here. You must select the appropriate download archive (.tar.gz) for your platform. You can select from either x64, x86, ARMv7 or ARMv8 builds depending on your system architecture. (Raspberry Pi 3B/3B+ users should select the ARMv7 package if running the 32-bit Raspian distribution.)

    > Monocle Gateway - Download Latest Release

    (We will use the x64 package in the following command line examples)

    $ wget https://files.monoclecam.com/monocle-gateway/monocle-gateway-0.0.3-beta%20%282018-07-28%29/linux/monocle-gateway-linux-x64-v0.0.3.tar.gz
    

    3.) Extract the contents of the archive file.

    $ tar -xvzf monocle-gateway-linux-x64-v0.0.3.tar.gz
    

    4.) Create a monocle system configuration directory.

    $ sudo mkdir /etc/monocle
    

    5.) Generate and download your Monocle API token from your user account page in the Monocle web portal.

    See this topic for more details on how to generate your API token: Monocle API Token
    Once you have downloaded your monocle API token file, move or copy it to the Monocle system configuration directory. (i.e. /etc/monocle/monocle.token)
     

    6.) Launch the “monocle-gateway” application from command line to verify its working properly.

    sudo ./monocle-gateway
    

    If Monocle Gateway starts up successfully and established a connection to the Monocle platform , then you will get a print out that looks similar to the following:

     ******************************************************************
     *             __  __  ___  _  _  ___   ___ _    ___              *
     *            |  \/  |/ _ \| \| |/ _ \ / __| |  | __|             *
     *            | |\/| | (_) | .` | (_) | (__| |__| _|              *
     *            |_|  |_|\___/|_|\_|\___/ \___|____|___|             *
     *                                                                *
     ******************************************************************
    
    -------------------------------------------------
    MONOCLE RUNTIME ENVIRONMENT
    -------------------------------------------------
    VERSION   = 0.0.3
    OS/ARCH   = win32\x64
    PROCESS   = monocle-gateway (PID=9652)
    TIMESTAMP = 2018-06-08T18:36:04.256Z
    
    -------------------------------------------------
    MONOCLE GATEWAY SERVICE         (Version: 0.0.3)
    -------------------------------------------------
    [Monocle Starting]
    [Monocle Connecting]
    [Monocle Started]
    [RTSP Server Starting]
    [RTSP Server Listening] 0.0.0.0:8555 (RTSP)
    [RTSP Server Listening] 0.0.0.0:443 (RTSP-TLS)
    [RTSP Proxy Started] (PID=468)
    [RTSP Server Listening] 0.0.0.0:8554 (PROXY)
    [RTSP Server Started]
    [Monocle Connected]
    [RTSP Server Registered]
    
    -------------------------------------------------
    MONOCLE RTSP SERVICE - INITIALIZED
    -------------------------------------------------
    FQDN = c5b4w3q2-bv4f-4sdf9-dsf-28a852ecae54.mproxy.io
    HOST = 192.168.1.22
    PORT = 443
    -------------------------------------------------
    

    Look for the MONOCLE RTSP SERVICE - INITIALIZED message; this means that everything was successfully and the gateway is fully running.
     

    7.) Configure one or more cameras for use with the Monocle Gateway service.

    The Monocle web portal has not yet been updated to include a user interface for configuring which cameras should use the Monocle Gateway service.

    Please see the Tagging Cameras for Monocle Gateway topic for the interim solution.
     

    8.) Test your configured cameras with the Monocle Gateway service.

    Now you are ready to test our your camera(s) using your Alexa device and Monocle via the Monocle Gateway. Just ask Alexa to show you one of your named cameras that have been configured to use the Monocle Gateway service.

    You should see the named camera displayed in the Monocle Gateway service command console followed by some details logging information as well as the camera stream displayed on your Alexa device.

    -------------------------------------------------
    INITIALIZE RTSP STREAM:  Kitchen
    -------------------------------------------------
     - NAME  : Kitchen
     - LABEL : PRIMARY
     - URL   : rtsp://192.168.1.251:554/cam/realmonitor?channel=1&subtype=0
     - UUID  : STREAM:99d01a23-c6sd-46-bb11-v1d9edda4523
     - SESS  : e28ba6f0-3c2a-481e-a715-4f989c615a0a
     - MODIF : Thu May 17 2018 16:38:55 GMT-0400 (Eastern Daylight Time)
    -------------------------------------------------
    
    2018-06-08T18:48:54.971Z [INFO]  [10.1.2.217:40172 <BJkj18ulm>] RTSP CLIENT SOCKET CONNECTED
    2018-06-08T18:48:55.103Z [INFO]  [10.1.2.217:40172 <BJkj18ulm>] RTSP CLIENT ATTACHED TO STREAM: Kitchen (STREAM:99d01a23-c6sd-46-bb11-v1d9edda4523)
    2018-06-08T18:48:55.120Z [INFO]  [10.1.2.217:40172 <BJkj18ulm>] RTSP ENDPOINT SOCKET CONNECTED {192.168.1.251:554}
    2018-06-08T18:48:55.130Z [DEBUG] [10.1.2.217:40172 <BJkj18ulm>] [CLIENT REQUEST]  --> [DESCRIBE] rtsp://c5b4w3q2-bv4f-4sdf9-dsf-28a852ecae54.mproxy.io:443/STREAM:99d01a23-c6sd-46-bb11-v1d9edda4523?session=e28ba6f0-3c2a-481e-a715-4f989c615a0a
    ...
    

    Once you have successfully tested your cameras, you can stop the Monocle Gateway service by pressing CTRL-C (you may have to press it several times) and then install Monocle Gateway as a service as demonstrated in the next topic.
     

    9.) Install the Monocle Gateway service daemon on your system

    The following command will install the Monocle Gateway service using systemd.

    $ sudo ./install.sh
    

    The install script will copy the required executables to the /usr/local/bin directory, copy the monocle-gateway.service file to the systemd configuration directory, create a monocle service user account, enable access to protected IP ports to bind to port 443 and enable the daemon to start on boot.

    (Feel free to review the install script prior to running the script to ensure you are comfortable with the actions/tasks performed.)


    Linux (systemd) Service Management

    The following commands can be executed in start, stop and restart the Monocle Gateway service daemon. You must run the command with sudo privileges.

    • Start the Monocle Gateway service:
      sudo monocle-gateway --start or sudo systemctl start monocle-gateway

    • Stop the Monocle Gateway service:
      sudo monocle-gateway --stop or sudo systemctl stop monocle-gateway

    • Restart the Monocle Gateway service:
      sudo monocle-gateway --restart or sudo systemctl restart monocle-gateway

    • Get the Status of the Monocle Gateway service:
      sudo monocle-gateway --status or sudo systemctl status monocle-gateway

    • Enable the Monocle Gateway service on system boot:
      sudo monocle-gateway --enable or sudo systemctl enable monocle-gateway

    • Disable the Monocle Gateway service on system boot:
      sudo monocle-gateway --disable or sudo systemctl disable monocle-gateway


    Logging

    If running the Monocle Gateway as a systemd service the application will write its output to the journald service.

    To monitor (“tail”) the log file while the service is running you can use the following command:
    sudo monocle-gateway --tail or sudo journalctl -f -u monocle-gateway


    Removal Instructions

    Uninstalling and removing the Monocle Gateway from the computer is very simple. You can use the uninstall.sh script included in the downloaded archive package to automate the remove of the Monocle Gateway service. This script will delete the executable binaries on the system, disable and remove the systemd service configuration and remove the monocle system user account.

    $ sudo ./uninstall.sh
    

    If you prefer to manually remove the service or don’t have access to the uninstall.sh script, you can run the following command to disable and stop the daemon service.

    $ sudo ./uninstall.sh
    

    Next, remove the privileged port access from the service executable:

    $ sudo setcap -r /usr/local/bin/monocle-gateway
    

    Then delete the following files:

    $ sudo rm /usr/local/bin/monocle-gateway
    $ sudo rm /usr/local/bin/monocle-proxy
    $ sudo rm /etc/systemd/system/monocle.service
    

    Next, remove the monocle system user account with the following command:

    $ sudo deluser --system monocle
    

    Lastly you can optionally remove the monocle.token file and monocle system configuration directory if you don’t plan on re-using it in the future:

    $ sudo rm -R /etc/monocle