homieiot / convention-website Goto Github PK

View Code? Open in Web Editor NEW

4.0 4.0 13.0 2.22 MB

The website and online validator for Homie

Home Page: https://homieiot.github.io/

License: MIT License

HTML 3.22% Python 2.10% Shell 0.05% JavaScript 4.86% SCSS 89.77%

convention-website's Introduction

Website

This repository contains the website sources for the Homie Website including the online validator javascript tool.

The build is triggered by a change in any of the Homie specification respositories and performed by Travis CI. The resulting webpage is uploaded to https://github.com/homieiot/homieiot.github.io/tree/master and is served by GitHub.

The generator in use is Hugo.

You can just call the ./build.sh script within this directory and find the page in the output directory site.

Manually generate the webpage

You need Hugo in the extended version (with sass/scss support).

The git grab utility requires python3. For a non-root environment, it is recommended to create a python virtual environment:

python3 -m venv dependencies
source dependencies/bin/activate

Install the dependencies gitpython, pyyaml, then run the git grab utility and and hugo last:

pip install -r requirements.txt
./grabrepos.py
hugo

Upload a manually generated webpage

The webpage lives within the "master" branch of https://github.com/homieiot/homieiot.github.io/tree/master. The generated "site" directory need to be pushed to that branch.

cd site
git init
git remote add origin [email protected]:homieiot/homieiot.github.io.git
git add .
git commit -m "Manually generated webpage"
git push origin -f HEAD:master

Data: FAQ, Maintainers

You find data files in the data/ directory. At the moment this is the FAQs and the maintainers file in yaml format.

Generated content files

All files in content/specification/ are automatically generated by the tool grabrepos.py. A file for each tagged version of the Homie Core convention is generated. Only those sections are considered that are mentioned in the multiversion.yml configuration file.

Preface documents, that are valid for all versions, are extracted from the develop branch and prefaced on every document by the Hugo generator.

Maintainer

Website maintainer: David Graeff [email protected]

convention-website's People

Contributors

Stargazers

Watchers

Forkers

boc-tothefuture thomdietrich fvdpol snewz mjcumming leifclaesson christian-me fkroepfl rroemhild clon1998 qwandor philrittenhouse ccutrer

convention-website's Issues

Travis not working

@marvinroger Could you please check if travis has organisation access? I cannot get it to work with the new Travis Marketplace Github App (which is different than the travis-ci github service from before).

It maybe only works for orga members, if that is the case, can you please go to the "Marketplace" in the top menu of Github, select travis, allow access and trigger a build for this repository. Thanks :)

Validator crashes

Hello,

pasting the following code into the validator results in a crash:

homie/device123/$homie 4.0
homie/device123/$name My device
homie/device123/$state ready
homie/device123/$extensions 
homie/device123/$nodes mythermostat
homie/device123/$state/set init

The exception printed to the JavaScript console is the following:

Uncaught ReferenceError: value is not defined
    homieverificator https://homieiot.github.io/js/main.min.js:54
    homieverificator https://homieiot.github.io/js/main.min.js:54
    onclick https://homieiot.github.io/tools/#:1
main.min.js:54:162
    homieverificator https://homieiot.github.io/js/main.min.js:54
    forEach self-hosted:206
    homieverificator https://homieiot.github.io/js/main.min.js:54
    onclick https://homieiot.github.io/tools/#:1

To be honest I am not sure if calling /seton a device property is even allowed, but I did not find anything about it in the specification.

Nevertheless this should not result in the validator crashing.

Allow non "homie/" prefix in online validation tool

IIUC, the "homie/" prefix can be changed to "X/" for branding reasons

If this root topic does not suit your needs (in case of, e.g., a public broker or because of branding), you can choose another.

However, the online validator will fail if this is changed:

reactor/device123/$homie 4.0
reactor/device123/$name My device
reactor/device123/$state ready
reactor/device123/$extensions 
reactor/device123/$nodes mythermostat

reactor/device123/mythermostat/$name My thermostat
reactor/device123/mythermostat/$properties temperature

reactor/device123/mythermostat/temperature 22 
reactor/device123/mythermostat/temperature/$name Temperature
reactor/device123/mythermostat/temperature/$unit °C
reactor/device123/mythermostat/temperature/$datatype integer

Fails with

Must begin with homie/

Webpage "ID Format" links do not work

Moved from homieiot/convention#131

None of the links that should go to the ID Format on the spec page work. They all link to https://homieiot.github.io/spec-core-v3_0_1/#topic-ids

Online verificator criticizes hyphen in topic

Examples [1] from spec lead to the warning [2] although the specs allows it [3]. The checking regex [4] seems to be the problem.

[1] homie/super-car/$homie "2.1.0"
[2] Device ''super-car' id does not conform to topic id restriction!
[3] Topic IDs [..] as well as the hyphen character (-).
[4] tool-verificator.js

Website doesn't build anymore

This is critical, but I do not have time to maintain the website at the moment.
Can anyone have a look at the CI? Seems like a python issue.

[Bug] Settable attribute is not specified in the example of the "Overview" section

Hi @davidgraeff!

I'm not sure if this issue belongs here, but I have noticed that, in the Overview section of the webpage (https://homieiot.github.io/), the provided example doesn't have the "settable" attribute defined for its "temperature" property. The example description states that "the target temperature can be read from and written to.", so settable should be set to true. At the same time, the "extension" device attribute is published, but this is not part of the latest stable release.

Thanks and best regards,

Aitor

Verificator bug in enum type

I've been writing a script to publish all my Domoticz devices in MQTT using the Homie convention.
The verificator detects an error in the following device. However, as far as I can tell, the device is correctly published and the payload is valid according to the specification. I've included the relevant part of for the validation and the 'error' detected by the verificator .

homie/domoticz/$state ready
homie/domoticz/$homie 4.0.0
homie/domoticz/$name Domoticz
homie/domoticz/$nodes 106
homie/domoticz/106/level 90
homie/domoticz/106/level/$name level
homie/domoticz/106/level/$datatype integer
homie/domoticz/106/level/$settable true
homie/domoticz/106/level/$retained true
homie/domoticz/106/selector [80] New
homie/domoticz/106/selector/$name selector
homie/domoticz/106/selector/$datatype enum
homie/domoticz/106/selector/$format Off,Movie/TV,Music,Game,THX,Stereo,Direct,Pure Audio,[0D] New,[80] New,[82] New,[0C] New,[0F] New
homie/domoticz/106/selector/$settable true
homie/domoticz/106/selector/$retained true
homie/domoticz/106/$name Onkyo - TX-NR646 Main Mode
homie/domoticz/106/$type selector
homie/domoticz/106/$properties level,selector

10	Property 'selector' value of type enum contains invalid data: '[80] New'. Must be one of 'Off,Movie/TV,Music,Game,THX,Stereo,Direct,Pure Audio,[0D] New,[80] New,[82] New,[0C] New,[0F] New'!

Verificator crash on $stats

The validator seems to crash with the following structure:

homie/device123/$homie 3.0
homie/device123/$name My device
homie/device123/$state ready
homie/device123/$nodes mythermostat
homie/device123/$stats/interval 60

homie/device123/mythermostat/$name My thermostat
homie/device123/mythermostat/$properties temperature

homie/device123/mythermostat/temperature 22 
homie/device123/mythermostat/temperature/$name Temperature
homie/device123/mythermostat/temperature/$unit °C
homie/device123/mythermostat/temperature/$datatype integer

it seems like it tries to match $stats as a string, which is not possible, since it gets parsed to an object.
The same happens with every $ nested structure like $fw and $implementation.

Design

I was thinking of a more professional looking, slick design like http://cbor.io/

Implementation guideline for client/controller developer

From @ThomDietrich on November 6, 2017 15:24

Derived from homieiot/convention#28 (comment)

Besides all the technical definitions of the Homie convention, we should give simple checklist-like instructions for developers on how to comply with the Homie convention. There are many (technical and logical) details that need to be handled, which are not easily described in the convention itself.

I believe the guideline will further clarify the benefits of the Homie convention and ease the adaption for unacquainted developers.

@marvinroger Please label with "help wanted"

Copied from original issue: homieiot/convention#51

Validator failure: Property '...' requires '$name' to be set

I'm confused why this fails:

homie/simple2-1/$homie 3.0.1
homie/simple2-1/$name MBMD
homie/simple2-1/$state ready
homie/simple2-1/$nodes meter
homie/simple2-1/meter/$name SIMPLE
homie/simple2-1/meter/$type Simple meters
homie/simple2-1/meter/voltagel1/$name L1
homie/simple2-1/meter/voltagel1/$unit V
homie/simple2-1/meter/voltagel1/$datatype float
homie/simple2-1/meter/$properties voltagel1
homie/simple2-1/meter/voltagel1 545427521536.000

Error:

n/a1	Property 'voltagel1' requires '$name' to be set!

Difference between OCF/Iotivity/WebThing API & Homie

From @echo1consulting on May 29, 2017 2:4

Hello, are you familiar with OCF and Iotivity?

It seems that there are similarities in the mission of Homie and OCF.

Copied from original issue: homieiot/convention#22

Validator does not allow negative values for floats

I get the following error

Property 'pressure' value of type float contains invalid data: '-73'!

when validating the following

homie/SPG9f374743ac/$name Smart Pool Gauge
homie/SPG9f374743ac/$homie 4.0.0
homie/SPG9f374743ac/$state ready
homie/SPG9f374743ac/$nodes gauge
homie/SPG9f374743ac/$extensions ""
homie/SPG9f374743ac/gauge/$name Gauge node
homie/SPG9f374743ac/gauge/$type ""
homie/SPG9f374743ac/gauge/$properties pressure,speed,alert,battery
homie/SPG9f374743ac/gauge/pressure -73
homie/SPG9f374743ac/gauge/pressure/$name pressure
homie/SPG9f374743ac/gauge/pressure/$datatype float
homie/SPG9f374743ac/gauge/pressure/$unit psi

Is there any reason negative values would not be allowed? I would assume so but the docs do actually say

Floats range from 2-1074 to (2-2-52)*21023

which is a somewhat garbled version of what's in the .md file: 2E-1074 to (2 - 2E-52) * 2E1023.
In both cases I think they should be prefixed by a +/-

I think the fix is simple enough. It looks like the optional minus sign is missing from the regex in the code:

          case "float":
                            if (!value.match(/^[\d\.]+$/))

Thanks,
Phil