Due to the large number of people having issues with tags Is there any interest if I volunteer to add some syntax checking and perhaps a bug fix is better than a warning for missing labels?
Thoughts?
My personal thoughts are improving documentation is a band aid, better to automate instead and use warning/errors in logs to clearly tell people what is wrong. Helpful if it is a basic typo, ie a tag called Lightning instead of Lighting could go on and cause hours of frustration when it is simple to pickup and flag in logs.
I think the challenge here is one binding’s invalid tag is another binding’s required tag. And since the format and the meaning of the tags is dictated by the bindings that use them (e.g. Google Assistant, Alexa) I’m not sure it is feasible to develop this in the cloud connector. I think you would have to add it to each of the bindings that use tags. Those are, IIRC
@matt1 I agree with you. I made this actually request over a month ago on git hub. The answer @rlkoshak gave here is similar to the answer I received. Here is the link: Issues in main openhab. The google people responded so I opened this issue: Google issue
I have not heard from the Alexa people except on docs. There position in my opinion was there was no issue. Basically they did not seem to understand my request.
In fact I am thinking that no one really understands what I went through and @matt1 is going through. It is such a simple thing to setup when it works, but when there is a problem it is a struggle! I spent days, so has Matt.
The request here was similar to mine update the cloud connector to somehow flag items that maybe could have a problem. Maybe each binding that uses it could add an xml or json requirements file to syntax check for.
The second position of the Alexa people is that their tags are based on the HomeKit binding. I believe the official google help doc has a similiar blurb. So really all the requirements are the same/ very similar at the present moment.
We have a volunteer, I would love to see if we can have the connector people maybe accept the help and see what he has to offer. I volunteered for the docs on the Alexa side, I bailed when met with total resistance from someone over there. Maybe not the correct thing to do by me, but I was trying to assist with something, just like @matt1 is here. We are both taking the opinion of we found an issue so instead of just complaining we want to improve so we offered solutions instead of just being part of a problem.
Yes if you took that approach I would call it a challenge, as that would still require changes to the cloud connector (on top of the three app you mentioned) and possibly the myopenhab.org server to add the ability to pass error messages back to the log files.
What I am suggesting is not a big challenge at all. Yes it would not prevent any of these issues from causing headaches for users, but it would allow yourself and others on this forum the ability to find the cause of the issues much quicker if people posted log outputs. For people that do check logs they would then not post and have saved hours of pulling hairs out.
I am NOT suggesting a syntax FILTER that removes anything from the data steam, instead I am suggesting a fail safe warning system that does not prevent new tags or in fact does not change any data that is passing through. A warning in the logs would get raised but the tag still is allowed to pass.
Perhaps a better definition is in order…
The problems:
All lower case tag names break “sync my devices”. eg [“lighting”] fails but [“Lighting”] works.
Smart quotes breaks any tag. Do not copy the tags above as they have smart quotes. EDIT: this actually does create a warning in 2.3 and the entire items file does not parse. Happy this is no longer an issue directly, but it will trigger number 5 if all your items are in the same file.
Missing labels from any items that include a tag breaks functionality.
The order you type the fields in causes things to break. eg tag must come directly before channel.
No tags at all in your items and it fails with no warnings and google will not even link.
A simple typo will cause it to fail with no warnings as to why or where to look. eg [“Lightning”]
Any corruption in the JSON database is not picked up with warnings, a number of users have posted where their item files are 100% fine but a glitch in the database has broken everything.
What I am proposing would drastically reduce that list down to be much shorter and would not stop new tags from passing through. A syntax checking system that does not change the data stream in any way, it only watches and makes comments in the logs for a users to respond to. This could be implemented ready for testing in as little as 24-48 hours time and does not require any changes to the myopenhab.org server, no changes needed to the 3+ applications which may require signing off from slow moving companies and does not stop any more advanced features from being implemented over time in those higher level pieces of the architecture.
The list of valid tags which some will break certain applications from working. In brackets the apps which can use the tags, taken from documentation…
Lighting (Alexa,Hue, Google, Homekit)
Switchable (Alexa,Hue, Google, Homekit)
CurrentTemperature (Google, Alexa, Homekit)
Thermostat (Google,Alexa,Homekit)
TargetTemperature (Alexa,HUE, Homekit)
homekit:HeatingCoolingMode (Alexa,Homekit)
Fahrenheit (Alexa, Homekit)
CurrentHumidity (Homekit)
Any missing, or any cause issues? please post to let me know.
@Thedannymullen, @matt1, I’m not arguing against making any change. However, tags are intended to be something that can be used by any binding for almost any purpose. Given this is the case, any syntax checking of the tags should be implemented in the bindings that use the tags.
That is all I’m saying. Perhaps there is some library that could be written that is shared across the bindings that are currently using tags based on the HomeKit nomenclature.
But tags are not limited to just those bindings that implement tags now nor are tags limited to the HomeKit nomenclature. Therefore is makes no sense to implement the syntax checking of the tags in the cloud connector. Because of this open nature of tags, the cloud connector does not and can never have the information necessary to determine whether a given tag may cause problems. But the bindings absolutely do know what tags are valid and what ones are not.
I agree with the problem. I agree that adding some checking would be fantastic and is sorely needed. I only disagree about where the checking can/should take place. I can’t get behind any solution that will limit the utility of existing tags. And flooding my logs with a bunch of warnings that don’t apply to me because I’m not using those bindings counts as decreasing the utility of tags.
For some or even all of the current bindings that use tags. But there is nothing preventing future bindings from requiring all lower case or something else. I think that would be stupid, but tags have been purposely left unconstrained because they are intended to be used for more than just identifying Items to share with Alexa and Google Assistant. I don’t think it would be correct for the Cloud Connector to identify those tags as “wrong” or with warnings just because the current set of bindings started using them first.
This can/should probably be handled by the Items parser itself perhaps. Smart quotes are not valid under any circumstances.
This is a problem for some bindings but not all bindings that can use tags. If it is a problem for a given binding, that binding should check for it and generate the warning there.
This is another one that should be handled by the Items parser. And this problem would occur at parse time so the cloud connector would never see these Items anyway so it can’t be identified there. I could be wrong but doesn’t it already reject the file if you put them out of order?
Not a problem for Alexa though. So this check should be made in the Google Assistant binding.
If the binding does the syntax checking of the tags then it can be very strict in what sorts of checking it makes and the errors can be very clear. In the Cloud Connector the best you can say is “if you happen to be using Google Assistant it might be a problem maybe unless they changed the binding and forgot to update the cloud connector and you can ignore this if you are using tags for some other purpose.”
Again, when the binding gets the Items with the tags it can check those tags and identify there is something wrong with quite a bit of specificity. It probably can’t tell you that your jsondb is corrupted but it can at least tell you what it thinks is wrong with the tags which should provide a clue (i.e. the binding sees a different set of tags from what is in the .items files). But since Items defined in .items files do not go into jsondb it isn’t clear to me what is actually happening here.
Can’t help with that one.
A perfect example for why the syntax checking needs to go in the binding that uses the tags, not in the cloud connector.
That sounds like a separate bug.
I agree. All of these problems can and should be addressed. But they need to be addressed in the binding that uses the tag, not by the cloud connector binding.
Flooding the logs with non-applicable warning messages actually does impede advanced features and uses of tags. I know some users who are using tags in unique ways in their Rules. So we are looking at hundreds to thousands of warning messages every time they change their Items. I can’t speak for them but that would piss me off to no end. If I were to write my own binding that uses tags and I keep getting warnings because the tags I need don’t conform to the tags Google Assistant wants I’d be very unhappy and file an issue to remove the tests you are looking to add.
Error messages and warning in the logs that are not relevant is an antipattern, IMHO.
I can’t address the problem of working with the other groups except to say that is the nature of development. Unless you are coding solo you have to work with other people and it’s a major pain.
I’m not a developer so I have no say in any of this. I’ll not discourage anyone from working on anything. But I do have opinions and based on my understanding of the purpose of tags, these problems with tags need to be addressed in the bindings that use the tags, not the cloud connector binding.
Some feedback on syntax. Some of these may be overkill but I am writing as part of brainstorming.brad
If item name and label is the same let people know it doesn’t have to be… This is because all the docs show it this was, makes people think you can’t have a friendly name they have to matc h. Note this is a very low low priority, but I saw many questions on it and was even confused myself once.
The quote spacing and brackets. If there is a required space between a quote and brackets then check it.
If using alexa etc. Don’t put [ %s ] inlabels. Alexa gets con fused.
Think that’s all I have for now. You covered the rest very well.
Funnily you are starting to describe what I have been suggesting all along. We only disagree on where the “library” lives
Niether would I, what I am proposing will not break existing or future tags.
I agree and that is easily solved as some smart people gave us the tools to create bindings which can be configured and have the log files changed to 5 different levels of output.
I actually really enjoy working on large projects with others, I learn and enjoy it. I have learnt from your reply here as well so thank you for your input. The only pain I get is from seeing people asking for help over and over on the same issues when they could begin to be addressed with very little work. If the bugs or lacking feature sets get implemented where you are suggesting, then great I am more than happy for my work to be thrown in the bin as it is no longer needed.
Would a push request to the documentation pages get accepted? Say a section called “known issues”. The documentation now has a version drop down list and it would be handy to have clear known issues for older builds as not everyone likes to upgrade.
My personal feeling on a matter like this:
Ofcouse! It´s obvious! . Anything that can help track any problem is welcome.
Specially now since I just ran into a problem with my Google Home last night and openhab. It has been working rocksteady for months. Now Google Home wont sync my devices due to an error with openhab cloud, (it says).
That is my point really. I think this is a fantastic idea and it needs to be done.
I can’t see why it wouldn’t be accepted. I don’t contribute to the docs nearly enough and am not a maintainer so I can’t speak for them and say definitely yes.
But again there might be some discussion/pushback depending on where you post it. Were these updates to the docs be placed in the cloud connector docs there might be puoshback. In this case, if I were having problems with Google Assistant, for example, it would never occur to me to check the cloud connector docs for troubleshooting tips. I would look at the Google Assistant binding’s docs since that is what I’m using and what I’m having trouble with. And until the text search inside docs gets fixed help would not be findable through search.
@rlkoshak on pushback of the docs. I received a little, I modified the amazon one. The pushback was bad, because if I were to follow it did not solve the documentation problem.
We need explicit documentation vs implied documentation. What I proposed was explicit and the pushback made it implied which is what we have now. For example if you look at openhab docs now they say:
The problem here is it implies that “Kitchen Switch1” has to be the same in the name and the label. Look through forum people have confused this.
I propose making docs like:
Item_Name_Here "Item Label here" (GroupHere) {channel info}
Real example:
Kitchen_Switch1 "Friendly Name Label Here" (Kitchen_sw_group) {channel info}
The second method clearly shows that spaces can be used in labels and they don’t have to be the same as the item name. I run across many openhab docs that make me really think, do these parameters have to be the same. Usually I start the same then rename after the fact.
I am happy people are coming on board to what myself and @matt1 are proposing.
Unfortunately there isn’t a whole lot that can be done about that. The maintainers of the bindings are also the maintainers of their own README. If they disagree with a proposal ultimately they get the final say as to whether a change gets merged or not. There can be a little bit of leverage applied at a high level by setting some standards (e.g. when Kai and company mandated that the OH 2.x bindings need to support manually created Things and have documentation in the README to tell us how to do it). But at the end of the day, no matter how good the idea is, if you can’t convince the binding maintainers to merge the change it won’t be merged.
I fail to see why they would have pushed back on this sort of addition but I’m sure they had some reason. One thing we have to remember is that the maintainers have their own vision and goals for where ESH, OH, and their binding is going. They also have insight into some things we don’t. So sometimes an idea is rejected, no matter how good, because it goes against the vision or roadmap they have for the binding, will result in more work in the future for the maintainers to keep up, boxes the developer into a certain path they are not yet ready to choose, etc.
For example, someone added a bunch of really good Linux examples to the Exec binding. But there is a standard that the bindings READMEs must be kept platform independent unless the binding is only supported on one platform. This is to avoid the huge amount of work to go and add platform specific examples to all the other bindings and should the way something works on a platform change have to go find all these places to update as well. So the examples were not merged in.
Yes I do feel I need to check if a PR to cover “known issues” will be allowed. In commercial projects I have worked in before it could be seen as the best option to “keep it hidden as it will be fixed soon”. The documents now have version drop down boxes so this would disappear when a new version is released with fixes and still allow older ver users to still access the info, brilliant feature if it gets used. This is not README files we are talking about…
But this is getting off topic to what I really wish to discuss which is if users will support it and who needs to be brought into this discussion to make a plan forward? If you agree something needs to change then please post in this thread.
The suggestion is to place a diagnostics mode into the cloud connector that can give feedback to users in their logs whilst keeping traffic OFF the myopenhab.org server and preventing the need for multiple large companies from signing off on changes ie the google home end of our code needs this from what I read once. No changes are needed to the myopenhab.org server and it allows testing to be done without effecting current users. Other suggestions would require far greater ranging changes and require input from multiple people who may be too busy doing other projects.
Even if there are no bugs, I still feel strongly that every binding should have a USEFUL debug or trace mode implemented to assist every user (and rikoshak) in helping them when they ask for help on the forum.
All of the binding documentation you see in the OH docs come from the README.MD file of the binding in openhab1-addons or openhab2-addons. For those bindings that come from ESH they come from the README.MD file from there. So they are README files we are talking about. That is how the docs get built. So ultimately, it will be the maintainers of that add-on who will be the ones approving and merging any changes to the documentation for their binding.
The version field I believe is active and working. When a new version of OH is released, the READMEs from the add-ons and the rest of the docs get frozen for that version and the latest version moved forward. This is managed by the openhab-docs repo.
I agree something needs to be done.
The maintainers of any add-on that you intend to modify the docs. If you want to try to go forward with making the changes to the Cloud Connector you need those maintainers. If you want to make the changes to the bindings that actually use the tags and define the syntax you need to bring in those maintainers. I think you can find them by looking at who is merging the PRs for that binding.
I would be prepared for pushback from the Cloud Connector maintainers though. I suspect they will feel, like I do, that it isn’t a job for the Cloud Connector.
Don’t agree with this one in peoples logs sorry, I believe it should be covered in the docs Thank you for trying to change it in the docs in the past.
There is no issue when I test on Openhab 2.3 stable and upwards, possible this was in older versions <2.3 but I have checked this many times to see if my issue was related. It works with and without the spaces for me.
Good suggestion, I would expect a discussion on this is on Github somewhere. One way around this would be for the user to implement the “fancy” dynamic label at the sitemap or habpanel level and not at the item level.
I just looked at what happens when this is added and the label at the REST api level is not effected in Openhab 2.3, so this may be something that was changed in 2.3? so perhaps check if it is still an issue. In openhab 2.3 the REST api returns this in a separate JSON key not part of the label…
So this could be detected and warned about if it still causes issues in 2.3 and newer. The warning could be made to only occur if the item is tagged and if using Alexa. This kind of thing is simple to add but it is possible this is no longer an issue. Can you confirm?
I changed one of my lights and sync’d with Alexa again. I put the %s in the name and deleted the space between "] in the lighting tag. All appeared to work with no issue. This makes me happy. Now I can possibly get rid of the duplicate labels between items and sitemaps.
Thank you for trying to change it in the docs in the past.