Package: openhasp-config-manager
openhasp-config-managerA cli tool to manage all of youropenHASPdevice configs in a centralized
place.Featuresunlimited multi-device managementshared configuration between devicesjsonl preprocessing, which allows for//comments within jsonl filesline breaks wherever you likejinja2 templating within object valueslocal and globally scoped variablesvalidation of common mistakes forjsonl objectscmd filessimple configuration upload to the device(s)automatic diffing to only update changed configuration filesgit-style diff output for changed linesAPI client (Web + MQTT)execute commands on a platelisten to events and state updates>openhasp-config-manager-h
Usage:openhasp-config-manager[OPTIONS]COMMAND[ARGS]...

Options:--versionShowtheversionandexit.-h,--helpShowthismessageandexit.

Commands:cmdSendsacommandrequesttoadevice.deployCombinesthegenerationanduploadofaconfiguration.generateGeneratestheoutputfilesforalldevicesinthegiven...helpShowthismessageandexit.listenSendsastateupdaterequesttoadevice.logsPrintsthelogsofadevice.screenshotRequestsascreenshotfromthegivendeviceandstoresit...shellConnectstothetelnetserverofadevice.stateSendsastateupdaterequesttoadevice.uploadUploadsthepreviouslygeneratedconfigurationtotheir...varsPrintsthevariablesaccessibleinagivenpath.DisclaimerTL;DR: This project is still experimental.I do use openhasp-config-manager exclusively to configure all of my openHASP devices. I am in the
process of adding tests to everything to make it more reliable and have also added lots of features along the way.
However, there are definitely still a couple of things that do not yet work as intended. Error logs
might need some love to be able to figure out what you did wrong. If you like the
project, feel free to open an issue or PR to help me out.How to useDockerdocker run -it --rm \
  --name openhasp-config-manager \
  --user 1000:1000 \
  -v "./openhasp-configs:/app/openhasp-configs" \
  -v "./output:/app/output" \
  ghcr.io/markusressel/openhasp-config-managerInstallationSince openhasp-config-manager needs some dependencies (seehere) it isrecommended to install it inside a virtualenv.venv-installvenv-installis a little helper tool to eas the
installation, management and usage of python cli tools in venvs.venv-installopenhasp-config-manageropenhasp-config-manager
openhasp-config-manager-hManualmkdir-p~/venvs/openhasp-config-manager
python3-mvenv~/venvs/openhasp-config-managersource~/venvs/openhasp-config-manager/bin/activate
pip3installopenhasp-config-managerAnd to use it:source~/venvs/openhasp-config-manager/bin/activate
openhasp-config-manager-h
openhasp-config-manageranalyze-c"./openhasp-configs"...Uninstalldeactivate
rm-rf~/venvs/openhasp-config-managerConfigurationopenhasp-config-manager is first and foremost a configuration
management system. Simply follow the basic folder structure and
config deployment will become trivial.Please read all of this,
as it is very important to understand the basic structure on
which everything relies.Folder StructureThe following folders should reside inside a single parent
folder, f.ex. namedopenhasp-configs. This folder can be
located anywhere you like, but must be accessible to
openhasp-config-manager when executing.common: Thecommonsubdirectory can be used for files
that should be included onalldevice. This folder is optional.devices: Thedevicesfolder is required. It must contain one
subfolder for each openHASP device you want to configure using
openhasp-config-manager. It is recommended to name subfolders according
to the physical devices associated with them.touch_down_1(example device folder)A device folder contains*.jsonl,*.cmdand other files which should
only be uploaded to that particular device.You can create arbitrary nested folder structures for organizing the files.
There is a limit to the file name length though,
seeFAQYou must provide aconfig.jsonfile, seeconfig.jsonfor more info.A more advanced configuration layout could look something like this:openhasp-configs
├── common
│   ├── content
│   │   └── card.jsonl
│   ├── dialog
│   │   ├── connected.jsonl
│   │   └── offline.jsonl
│   ├── navigation_bar.jsonl
│   └── page_header.jsonl
└── devices
    └── touch_down_1
        ├── 0_home
        │   ├── 0_header.jsonl
        │   ├── 1_content.jsonl
        │   └── page.cmd
        ├── 5_about
        │   ├── 0_header.jsonl
        │   ├── 1_content.jsonl
        │   └── page.cmd
        ├── boot.cmd
        ├── config.json
        ├── offline.cmd
        └── online.cmdconfig.jsonopenhasp-config-manager makes use of theconfig.jsonon your plate. It can extract information
from it to detect things like screen orientation, and also allows you to deploy changes within theconfig.jsonfile. Sincethe official API does not support
uploading the full file, only settings
which can also be set through the web ui on the plate itself are currently supported.To retrieve the initial version of theconfig.jsonfile you can use the
built-in file browser integrated into the webserver of your openHASP plate, seeofficial docs.The officialconfig.jsonfile doesn't provide enough info for openhasp-config-manager
to enable all of its features though. To fix that simply add a section to the
file after downloading it:{"openhasp_config_manager":{"device":{"ip":"192.168.5.134","screen":{"width":320,"height":480}}},"wifi":{"ssid":"Turris IoT",...}Config File Preprocessingopenhasp-config-manager runs all configuration files through various preprocessors, which allow us to use
features the original file formats do not support by themselves, like f.ex. templating.Multiline JSONL filesWhile the JSONL file format requires each object to be on a single line, openhasp-config-manager
allows you to add as many line breaks as you wish. This makes it much easier to edit, since a config
like this:{"page":0,"id":31,"obj":"msgbox","text":"%ip%","auto_close":5000}will be deployed like this:{"page":0,"id":31,"obj":"msgbox","text":"%ip%","auto_close":5000}CommentsNeither JSON nor JSONL allows comments, but openhasp-config-manager does!
You can mark comments by prefixing them with a double forward-slash:// File description
{
  // Object Description
  "page": 0,
  "id": 31,
  // Property Description
  "obj": "msgbox",
  "text": "%ip%",
  "auto_close": 5000
}TemplatingYou can use Jinja2 templates inside all jsonl object values. To access the value of another object in a
template, you can use thepXbYsyntax established by openHASP, whereXis thepageof an object andYis itsid. openhasp-config-manager even tries to resolve templates that lead to other templates.
Be careful not to create loops in this way though.You can use the full functionality of Jinja2 like f.ex. math operations, function calls or type conversions.{"page":1,"id":1,"x":0,"y":0,...}{"page":1,"id":2,"x":"{{p1b1.x}}","y":"{{p1b1.y+10}}",...}VariablesBesides accessing other objects, you can also define custom variables yourself, which can then
be referenced inside of templates. Variables are defined using*.yamlfiles. If you
decided to use a subfolder structure to organize your configuration files you can use these folders
to also set the scope of variables. More specific variable definitions (longer path) will override
less specific ones.GlobalGlobal variables can be specified by creating*.yamlfiles inside the root config folder (f.ex.openhasp-configs).Example:openhasp-configs/global.vars.yamlabout:page_title:"About"To access this variable, use a Jinja2 template:openhasp-configs/common/about_page.jsonl{"page":9,"id":1,..."title":"{{ about.page_title }}",...}Device specificDevice specific variables can be specified by creating*.yamlfiles inside any of the sub-folders
of adevicefolder.NoteDevice specific variables will override global variables, given the same name.Example:openhasp-configs/device/my_device/device.vars.yamlpage_title:"MyDevice"openhasp-configs/device/my_device/some_folder/some_page.jsonl{"page":1,"id":1,..."title":"{{ page_title }}",...}openhasp-configs/device/my_device/some_other_folder/some_page.jsonl{"page":2,"id":1,..."title":"{{ page_title }}",...}Printing variablesIf you are not sure what variables are accessible in a given path, you can use thevarscommand, which will give you a copy&paste ready output of all variables for a
given directory:>openhasp-config-managervars-copenhasp-configs-pdevices/touch_down_1/home
common.navbar.first_page:1common.navbar.last_page:4...
header.title:HomeDeploymentTo deploy your configurations to the already connected openHASP devices, simply use thegenerate,uploadordeploycommands ofopenhasp-config-manager.Noteopenhasp-config-manager needs direct IP access as well as an enabled webservice on the plate
to be able to deploy files to the device. To enable the webservice
try:openhasp-config-manager cmd -d plate35 -C service -p "start http"Run commandsWhile openhasp-config-manager is first and foremost a config management system,
it also allows you to run commands on a device by issuing MQTT messages without the need to install a separate
MQTT client first. Note that the MQTTserverstill needs to be running and also has to
be reachable from your local machine for this to work.For a list of possible commands to send to a device, take a look at the official
documentation:https://openhasp.haswitchplate.com/latest/commands/>openhasp-config-managercmd-c./openhasp-configs-dplate35-Cbacklight-p"{\"state\":\"on\",\"brightness\":128}"FAQHow do I see device logs?Try thelogscommand (this does require network access to the device):>openhasp-config-managerlogs-dplate35If that doesn't work, open a terminal and run the following command with the device connected via USB cable:bash-c"screen -q -L -Logfile device.log /dev/ttyUSB0 115200 &> /dev/null; tail -F device.log; killall screen"Output file name length must not exceed 30 charactersIf you want to organize your files (both common and device-specific ones) you can
simply create subfolders to achieve your desired structure. However, due to a technical
limitation openHASP does not support subfolder on the actual device. To overcome
this limitation openhasp-config-manager will automatically generate a file name for
files in subfolders before uploading them to the device..jsonor.cmdfiles within subfolders
will be renamed by concatenating their full subpath using an underscore (_) as a separator. So f.ex.
the file in the following structure:openhasp-configs
└── devices
    └── touch_down_1
        └── 0_home
            └── 0_header.jsonlwould be uploaded to thetouch_down_1device with the name0_home_0_header.jsonl.ContributingGitHub is for social coding: if you want to write code, I encourage contributions
through pull requests from forks of this repository. Create GitHub tickets for
bugs and new features and comment on the ones that you are interested in.Licenseopenhasp-config-manager is free software: you can redistribute it and/or modify
it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.