SNMP binding documentation is a bit outdated

Add-ons Bindings
, ,
1

I was experimenting with the SNMP binding and discovered the documentation is a bit outdated:

http://docs.openhab.org/addons/bindings/snmp1/readme.html#item-configuration

At least in my install of openHAB 2.1 i am able to bind string items to SNMP as well.
This item definition properly shows the port description of my TP-Link SG3424 switch.
(IP Adress replaced with x.x.x.x)

String switch1p17name "switch1 port 17 [%s]" <ethernet> (gswitch1) { snmp="<[x.x.x.x:public:.1.3.6.1.4.1.11863.1.1.3.2.1.1.1.1.2.17:10000]" }
2

Please file an issue on the openhab1-addons github project. The docs should match the binding’s capabilities.

3

@rlkoshak: what is the correct way to deal with this?

a) Update the OH2 docs entry for the binding and leave the OH1 wiki entry behind?
or
b) Update the wiki and then “sync” docs.openhab.org?

pinging @ThomDietrich and @watou also

4

My understanding is that the binding docs in the OH2 docs entry are generated by the docs in the actual binding’s repo so it definitely needs to be changed there.

At some point, we will need to cut support for the OH 1 wiki. I’ve already seen some differences between the wiki (e.g. the dmx binding OH 2 docs reference services/dmx.cfg) and some OH 1.x binding docs in the OH 2 docs. I don’t know if we are at that point yet but suspect sometime soon we will need to slap a big “deprecated” label on the wiki and point users to the OH 2 docs.

5

If I am not wrong, @watou created a copy of the wiki entries in the past:

Also: Migrate 1.x add-on docs from wiki to README.md files? - #11 by watou

so, if someone updates the wiki, the docs will not be updated (I don’t think that there is somekind of auto-update/sync of content in place)

I think that the same applies for the readme.md from the binding: openhab1-addons/bundles/binding/org.openhab.binding.snmp at main · openhab/openhab1-addons · GitHub

6

Correct, I did not mean to imply this.

The binding docs are not hosted in the openhab-docs repo. My understanding is that they are copied over and reformatted for use in the OH 2 Docs from the addons repos the same way the ESH docs are copied over during the nightly builds. So where ever they are copied over from is where the content needs to be updated.

7

wait… (I am not sure if I got it right… I am not so familiar with github)

This entry: https://github.com/openhab/openhab-docs/tree/gh-pages/_bindings/snmp1

is actually a “link” to https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.snmp/README.md …

right? (or it is a “standalone” entry? that is copied over periodically)

so if I update the README.md in the binding, it will show up in http://docs.openhab.org/addons/bindings/snmp1/readme.html ?

8

Correct.

To clarify:

Binding documentation is always updated within the binding repo.
The intention is, that everything that is related to a binding stays in one repo and you don’t have to change something “here” and then have to add something “there”.

This is also Explained in the readme file of the openhab-docs repo.
See this section:

So the issue has to be in the addons repo.
If the binding readme gets updated it will be in the documentation a bit later,
when binding doc entries are generated from those other repos next time.

2 Likes
9

I will file the issue as soon as i did some further testing (hopefully this weekend).

I want to know, if String items also work for setting the values. (That’s my intend, to easily set the port description to the real patched connection with a Selection in the sitemap.)

10

I filed the issue, hopefully i did it correctly. :wink:

1 Like
11

:slight_smile: It was unclear also for me (that’s why I opened the discussion above)

Well… since the docs entry for SNMP is updated from the binding readme which maintained in the openhab1-addons repository, you should have opened the issue against the addons repo :slight_smile:

https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.snmp/README.md

Go to https://github.com/openhab/openhab1-addons/issues and open up the issue there (the same). Close the issue #442 in the docs repo :slight_smile:

The openhab-docs repository keeps a “copy” of the SNMP binding readme file. Changes should be done in the binding readme and then they will be propagated to the docs repo.

12

Next try :joy:

13

very correct now ! :smiley:

You can also edit the new issue #5251 and add the link to the binding readme.md (just above the docs link):

https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.snmp/README.md

This is the “master” entry where the changes should happen with a Pull Request. The docs entry “pulls” info from there.

If you would like to go the “extra mile”, create a Pull Request with the proposed changes to the README.md file by editing it online in github:

edit.jpg1117×526 107 KB

14

Did it.

Not really used to git, i’m still using the good old svn for my projects.

Hopefully i don’t kill the build with my pull-request. :joy:

1 Like
15

don’t worry, it will be reviewed by the maintainers and if all is good, they will merge it :slight_smile:

I have proposed some PRs in the past and I got a lot of reviews (that’s good). I still have a lot that I haven’t progressed :frowning:

hint: in your PR #5252, mention:
Closes: Issue #5251

(this creates a connection between the fix (PR) and the issue)

edit: you already got a comment: https://github.com/openhab/openhab1-addons/issues/5251#issuecomment-315529752 :slight_smile: