Create a simple working system


    This is a description to come to a working setup of eGeoffrey.

    My starting point is a Raspi 3B+ with the Raspberry Pi OS on USB-stick instead of on SD card.

    Raspi is configured to interface via "VNC" and via "SSH".

    In my house I have a network with several WiFi access points connected to the wired LAN.

    During installation of the OS on the Raspi, my network server allocated an IP-address to the Raspi via DNS. I do not provide fixed IP-addresses. The validity (lease-time) of the addresses the server provides is very long.

    On that server an MQTT broker, mosquitto, is also always running. I am using MQTT for data exchange between decoders and any appliance using those data.

    Once the Raspi is up and running only every now and than access to it is needed. The easiest way to do that is using SSH via the terminal window on a network client. A second way is using a VNC viewer on a network client.

    Configuration of eGeoffrey is done via web-browser.


    A pushbutton is connected to a decoder. This decoder consists of an ESP8266 module placed on a PCB with connectors to hook-up sensors or actuators like a pushbutton.

    To be sure that the decoder is on-line it generates a "heartbeat" signal. As soon as this heartbeat is not received by eGeoffrey he sends us a call for attention.

    When a pushbutton is activated this event is shown on the eGeoffrey webpage.

    We interact with eGeoffrey with a network client or smartphone.

    Installing eGeoffrey

    Connect monitor, keyboard and mouse to the Raspi and turn the power on.
    Open a terminal window on the Raspi.

    Use "sudo" to issue the commands.

    Issue the command:

    sudo bash -c "$(curl -ssl"

    Now lean back and wait until several software packages have been downloaded and installed.

    Three times a question is posed. Just hit "return".

    To see if everything is OK in the terminal window goto the "egeoffrey directory". Issue the command:

    cd egeoffrey

    Now issue the command:

    sudo egeoffrey-cli status

    It takes some time but than you have an overview of the status of the different software modules of eGeoffrey.

    The status of each component should read "Up".

    To see if the website of eGeoffrey is also up and running, on a separate machine log-in to the network of which the Raspi is a user. Point a web-browser to the IP-address of the Raspi by inserting the IP-address in the URL field of the browser.

    It might take a little bit longer than you are used to but the welcome page of the eGeoffrey website should be presented. Standard you are logged-in as "guest".

    If you see "bells and whistles" eGeoffrey is OK.

    Close the browser.

    Now we have to proceed to extend the standard eGeoffrey with the "mqtt" module.

    Go back again to the Raspi and in the terminal window in the "egeoffrey directory" issue the command:

    sudo egeoffrey-cli install egeoffrey-service-mqtt

    than issue the command:

    sudo egeoffrey-cli start

    Now the actual download and install procedure starts.

    Lean back again until everything is ready.

    To see if everything is OK just request the status of eGeoffrey again. Issue the command:

    sudo egeoffrey-cli status

    Again everything should be "Up".

    This concludes the installation of eGeoffrey. If no surprises pop-up it is a piece of cake!

    Configuration of eGeoffrey

    To start with one has to think about how eventually all your sensors are grouped together to keep an overview.

    Lets create a structure according to reality.

    The sensors are spread through the house, are in the garden and in the barn.
    So the top level of my overview would be: house

    Beneath that level I have the different rooms, the garden and the barn:

    • living

    • kitchen

    • garden

    • barn

    and so on.

    Than each sensor/actuator requires a unique identifier:

    • living/pushbutton

    • living/temperature

    • living/airconditioner

    and so on.

    First of all it is important to test if signals of a pushbutton are entering eGeoffrey correctly.

    To simulate this open a terminal window on a separate network client.

    Issue the command:

    mosquitto_sub -h "IP-address of Mosquitto" -v -t /#

    which reads in my case:

    mosquitto_sub -h -v -t /#

    What is happening here is that in this window we subscribe on Mosquitto at address while the complete topic is presented for all topics.

    Open a second teminal window on the same machine.
    Issue the command:
    mosquitto_pub -h "IP-address of Mosquitto" -t /living/pushbutton -m 1

    which reads in my case:

    mosquitto_pub -h -t /living/pushbutton -m 1

    Here we publish on Mosquitto at in topic "/living/pushbutton" the message "1".

    When this command is given, in the other terminal window the message is displayed. This means that Mosquitto is sending the message correctly.

    Be sure that the topic sequence starts with "/" otherwise no message is received.

    In eGeoffrey goto "House/Sensors".

    Click on the second blue bar to register a new sensor.

    Window Sensor Configuration:

    Tab "General":
    Sensor identifier: "livingroom/pushbutton".
    Sensor description: "Button in the living"
    Icon: "wave-square" from the "Icons" table under "eGeoffrey".

    Tab "Data":
    Format: "Integer"

    Tab "Processing":
    Retention Policies: single_value – Retain the latest value only.

    Tab "Service":
    Associated service: mqtt: Interact with sensors through a mqtt broker.
    How to interact with the service: Push – the sensor will periodically provide new data.

    Tab "Configuration":
    The topic to subscribe: /living/pushbutton

    Caution: the topic starts with "/"


    After a few seconds the sensor is displayed.

    Go to "eGeoffrey/modules". Goto "service/mqtt". Pull-down "Edit Configuration".

    Window Module Configuration

    The MQTT Hostname to connect to: IP-address of your broker. In my case
    The port of the MQTT broker: 1883 (leave as is)
    I do not use authentication on my broker so the next two fields stay empty.


    Tick "Debug" on the line "service/mqtt". By doing this you evoke that the topic of an incoming message is displayed in the log.

    Go to "eGeoffrey/Logs". At the right top click "Clear" do do away with log entries which are already on the screen.

    Now publish the message in the terminal window. In the second terminal the incoming message is displayed. In the "Logs" window of eGeoffrey you see an "info" line with the message received by the sensor. Also a "debug" line is presented with more details about the message i.a. the topic of the message.

    Now we know that eGeoffrey is receiving our test messages.

    If we want to see the other value of the widget, just publish the message again but now with "0" instead of "1" after "-m ".


    The next step is to configure the presentation of the message.

    We need a menu structure to organise our display system.
    The top-level is called "Section". The level below that is called "Menu Item".

    There are two ways to create the structure: bottom-up, starting with the sensor or top-down, starting with the house.

    I prefer the top-down way.

    Go to bottom left to the "Edit menu" button. Select "New Section".

    Window Menu Section Configuration

    Section Identifier: "House"
    Text: "House"
    Icon: "dungeon"
    Order of this section: "10"


    Go to bottom left to the "Edit menu" button. Select "New Menu Item".

    Window Menu Item Configuration

    Section Identifier: "House"
    Menu item identifier: "Living"
    Text: "Living"
    Page: "Living"
    Icon: "couch"
    Order: "1"


    Go to bottom left to the "Edit menu" button. Select "New Menu Item".

    Window Menu Item Configuration

    Section Identifier: "House"
    Menu item identifier: "Kitchen"
    Text: "Kitchen"
    Page: "Kitchen"
    Icon: "mortar-pestle"
    Order: "2"

    Go to bottom left to the "Edit menu" button. Select "New Menu Item".

    Window Menu Item Configuration

    Section Identifier: "House"
    Menu item identifier: "Garden"
    Text: "Garden"
    Page: "Garden"
    Icon: "carrot"
    Order: "3"


    Go to bottom left to the "Edit menu" button. Select "New Menu Item".

    Window Menu Item Configuration

    Section Identifier: "House"
    Menu item identifier: "Barn"
    Text: "Barn"
    Page: "Barn"
    Icon: "toolbox"
    Order: "4"


    Now the menu is ready.

    The next step is to accommodate our push button in the living.

    Go to "Examples/Widgets showcase". Hit "New Page".

    Window Create new page

    Page Identifier: "Living"
    On page top click "add row"
    Give this row a title: "Living"
    Row title can be deemed to be the title of the page with displayed widgets.

    Click "add widget".

    Window Widget configuration

    Tab "General"
    Widget title: "pushbutton"
    Size of widget: "2"
    Widget type: "status"
    Widget offset: "2"

    Tab "Status"
    Sensor: "living/pushbutton"


    eGeoffrey is calling

    It is important to know that the decoder is still on-line.
    For this reason we introduce a "heartbeat signal". This is a "pulse" sent by the decoder on a regular basis as long as the decoder is OK. In my system I do the following:
    send a "1" every ten seconds
    send a "0" a quarter of a second later

    The first step now is to create a widget in eGeoffrey to display this signal.
    But that is not all. We would like to receive an alert as soon as the heartbeat stops coming in. The reaction on the heartbeat failing is created using a "rule".
    That alert has no value sitting in eGeoffrey without somebody noticing it.
    The next step will be to have eGeoffrey send an email notice that eGeoffrey needs attention.
    At last the smartphone is used to interact with eGeoffrey.

    When a decoder stops working, eGeoffrey sends an email message. With an email client on your smartphone you receive this message. With the web-browser on your smartphone you can have a look what is going on.

    Configuration of the heartbeat signal

    Create sensor

    Go to "ADMINISTRATION/House/Sensors", Click on blue bar "+ Register a new sensor".
    Window Sensor Configuration

    Tab "General"
    Sensor Identifier: "living/heartbeat"
    Sensor Description: "living heartbeat signal"
    Sensor Icon: "heartbeat"

    Tab "Data"
    Format: "Integer"

    Tab "Processing"
    Retention Policies: "single value"

    Tab "Service"
    Associated Service: "MQTT"
    How to interact with the Service: "Push"

    Tab "Configuration"
    The topic to subscribe: "/living/heartbeat"


    When the signal is already being sent, go to "eGeoffrey/Logs". Here you should see the signal coming into eGeoffrey through the new sensor.

    Present signal

    Go to "MY HOUSE/House/Living" page. Top right click "Edit Page". Click "+ Add Widget".
    Window Widget configuration

    Tab "General"
    Widget Title: "living/heartbeat"
    Size of widget: "1"
    Widget type: "Heartbeat – display an elapsed since last heartbeat"
    Widget offset: "1"

    Tab "Heartbeat"
    Sensor: "living/heartbeat"


    Go to top right. Click "Save Changes".

    Now every ten seconds, the frequency of the heartbeat, the heartbeat icon changes colour from grey to green for the duration of the pulse.

    Monitoring the heartbeat signal

    Go to "ADMINISTRATION/House/Rules". Click on blue bar "+ Add a new Rule".
    Window Rule Configuration

    Tab "General"
    Rule Identifier:"living/heartbeat"
    Rule text:"Living heartbeat supervisor"
    Severity: "Warning"
    Type: "Recurrent – schedule rule's execution through the Schedule tab"

    Tab "Constants"
    Click "+Add Constant"
    name of the constant: "value_off"
    value of the constant: "0"
    Click "+Add Constant"
    name of constant: "elapsed_threshold"
    value of constant: "0"

    Tab "Variables"
    Click "+Add Variable"
    name of the variable: "value"
    reference of the sensor: "living/heartbeat"
    Click "+Add Variable"
    name of the variable: "value_elapsed"
    reference of the sensor: "ELAPSED living/heartbeat"

    Tab "Conditions"
    Click "+Add Condition"
    condition: "value == value_off"
    Click "+Add Condition"
    condition: "value_elapsed > elapsed_threshold"

    Tab "Schedule"
    seconds: "20"

    To test if the rule is working, the conditions need to be met.
    Until now the heartbeat signal was arriving. Just suppress this signal.

    Because at this moment the ELAPSED command is working with an interval of minutes, it will take a minute for eGeoffrey to react on the fact that the heartbeat signal is not arriving anymore.

    Go to "eGeoffrey/Logs". After a minute from the time you suppressed the heartbeat signal in the upper right corner a warning signal will pop-up reading "Living heartbeat supervisor". After a second or so this alert disappears again. The counter of the alerts is increased.

    In the log a line reads: "[controller/alerter] [living/heartbeat][warning] Living heartbeat supervisor"

    Now monitoring of the functioning of the decoder in the living is working.

    Installing the SMTP service

    Got to "eGeoffrey/Marketplace"
    Scroll down until you see "egeoffrey-notification-smtp"
    Click on it.
    On the page where you land you are in the paragraph "Install"

    There you find the command which needs to be executed: "egeoffrey-cli install egeoffrey-notification-smtp"

    This command has to be executed on the Raspi with eGeoffrey installed.

    The simplest way:
    Open a terminal window on your network client.

    Issue the command:
    ssh pi@Raspi IP-address (in my case:

    ssh pi@

    You are requested to insert the password of the Raspi. Insert it.
    Now you can access eGeoffrey.

    Issue the following commands successively:

    cd egeoffrey
    sudo egeoffrey-cli install egeoffrey-notification-smtp
    sudo egeoffrey-cli start
    sudo egeoffrey-cli status

    Now also "egeoffrey_egeoffrey_notification-smtp_1" should be UP.

    Close the terminal window.

    Configuration of the SMTP notification service

    Go to the eGeoffrey web-interface.
    Go to "eGeoffrey/Modules".
    Scroll down to "notification/smtp". Go to "Actions/Edit Configuration"
    Window Module Configuration

    Tab "notification/smtp"
    Below I insert values comparable with my situation. You have to take your equivalent values.

    The email address used as from of the message: ""
    The SMTP server used to send out the email: ""
    The port of the SMTP server: "587"
    The username for authentication against the SMTP server: ""
    The password for authentication against the SMTP server: "your password"
    Use TLS: in my case "tick in the box"
    Recipient email address(es), comma separated: ""
    Subject of the email: "eGeoffrey is calling"
    Template to use for the email's body (with placeholders: "Your attention is required"

    Tab "Notification Settings"
    Ignore notifications if below this severity: "warning"

    The rest of the fields as you wish.


    Go to "notification/smtp/Actions/Send Notification"
    Window Type in the value you want to notify about

    Insert "test"


    In the recipient email in-box you should receive an email message from eGeoffrey.

    The SMTP notification service is up and running.

    The last test is to suppress the heartbeat signal. Wait about a minute and then eGeoffrey will send you an email notification.

    Use your smartphone

    On your smartphone you can access eGeoffrey if you are via WiFi connected with your LAN. Just use the web-browser on it.
    If you added the email account to which eGeoffrey sends his calls to your email client eGeoffrey will notify you when required.

    Have fun!

  • FANTASTIC detailed step by step How To, thanks a lot for this amazing contribution, would boost for sure new users to quickly get started with eGeoffrey! Thanks again

Log in to reply