Very lightweight daemon to publish smart home data to a MQTT broker (1wire data as temperatures, ISP real time consumption, UPS figures, meteo forcast, ...), check subscribted ones and alerts if out of range or missing. Custom decision scripts can be created in Lua.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Samples/CorrectTemp
scripts
src
startup_scripts
.gitignore
DevNote
LICENSE
Makefile
Marcel.conf
README.md
remake.sh

README.md

Marcel

Marcel is a lightweight versatile daemon to

  • publish easily some figures to an MQTT broker (1wire probe values, UPS, ...)
  • watchdog on published data
  • custom checks can be implemented through Lua scripts
  • finally send SMS, mail or Google Cloud Messages in case a test failed and then when it recovers.

#Requirements :#

#Compilation :#

  • Get Marcel latest tarball for stable version or clone its repository for development version

  • Install PAHO library for C ( https://eclipse.org/paho/clients/c/ )

  • curl is needed as well to send SMS

  • Compile Marcel

    make

You may modify the Makefile to add or remove following compiler options :

  • -DFREEBOX : Enable Freebox v4/v5 figures publishing (French Internet Service Provider) (v1.1+)
  • -DUPS : Enable UPS monitoring. Query NUT through its Telnet interface to retrieve UPS figures. (v1.2+)
  • -DLUA : Enable Lua user function (v3.0+)
  • -DMETEO : Enable meteo forcast publishing (using OpenWeatherMap.org) (v4.1+)
  • -DRFXTRX : Add support of RFXCom transceiver (v4.7+)

##Note :## This Makefile is automatically generated by my old (but still useful :) ) LFMakeMaker. I strongly suggest to modify then launch remake.sh instead of tedious Makefile changes.

#Configuration :# By default, Marcel reads /usr/local/etc/Marcel.conf as configuration file (may be changed using command line option -f). Have a look on provided file which contains comprehensive explanations of all known directives.

##Notez-bien :## Starting v6.0+, each sections in the configuration file must be uniquely named.

#Lua custom methods :# Following methods are exposed to Lua code through Marcel object :

  • Marcel.MQTTPublish( topic, value [, retain] ) : Publish a value to MQTT broker. If retain = true, the message is kept.

  • Marcel.RiseAlert( topic**,** message ), Marcel.RiseAlertSMS( topic**,** message ) : Tells Marcel about an alert condition

  • Marcel.ClearAlert( topic ) : Clear an alert condition

  • Marcel.SendMessage( title , Text ) and Marcel.SendMessageSMS( title , Text ): The 1st one sends a message using AlertCommand facility which is generally used to send a mail. The 2nd one uses also SMSUrl which is generally used to send an SMS.

  • Marcel.SendNamedMessage( names , title , Text ): Sends a named notification (see bellow).

  • Marcel.Hostname() : As the name said, host's name

  • Marcel.ClientID() : Configured MQTT client id

  • Marcel.Version() : Marcel's version (have a look on scripts/AllVerif.lua for an usage example)

Notez-bien : Marcel is able run only one Lua function at once. Consequently, your functions have to be as fast as possible.

#Enable / Disable a section

Starting v6.03, it is possible to enable / disable individually sections.

To do that, send to MarcelID/OnOff/section_name :

  • 0, Off, Disable : Disable corresponding section
  • any other value : Enable corresponding section

#Installation :# A startup script for OpenRC has been provided in sub-directory ... startup_scripts.

#Launch options :# Marcel knows the following options :

  • -h : online help
  • -v : verbose output
  • -f : loads as configuration file. The default one is /usr/local/etc/Marcel.conf
  • -t : test configuration file and exit

Have a look on provided configuration file to guess the syntax used (I'm busy, a full documentation will come later).

#Alerts vs Notifications

  • Alerts respond to 'Alert/...' topics
  • Notifications respond to 'Notification/...' topics

If the first character of the payload is an 'S' or 's' it's meaning an alert is raising and a communication will be send only if it's not an already open alert. A payload not starting with 'S' or 's' means the alert is closing.

Unlike Alerts, Notifications are not checked against duplication : in other words, communication are unconditionally sent.

  • S : both SMS and Mail will be send
  • s : only Mail will be send

#Named notifications# Named notifications are declared using $alert= configuration directive as

$alert=N
SMSUrl=http://api.pushingbox.com/pushingbox?devid=xxxxxxxxxxx&msg=%s
AlertCommand=mail -s "%t%" mail@domain.com

The argument of the section, a single character, is the name of the alert. In the example above, it's 'N'. It has to be followed with an SMSUrl= or AlertCommand= describing the action(s) to do. Have a look on provided Marcel.conf to see the syntax use. Notez-bien, both directives can be present and in this case, both actions are done.

Named notifications are raised using

  • Lua's Marcel.SendNamedMessage( names , title , Text )
  • sending a message to nNotification/names/title topic.

names is a string on which each and every characters correspond to the name of an alert to raise. As example, if names=ABC means that alerts A, B and C will be sent.

#Logging# As of version 6.05, Marcel publish its loggings to following topics : MarcelID/Log/severity with severity one of :

  • Fatal (crash of Marcel or functionality loss)
  • Erreur (something went wrong but it didn't impacted Marcel's health)
  • Warning (something you must be aware of)
  • Information (all others)

#Side note# The name is a tribute to my late rabbit that passed away some days before I did started this project : he stayed at home as keeper. RIP.

Written with StackEdit.