Documentation #421
Replies: 134 comments
-
|
We definitely need this. Another thing is to add informations from official HomeKit docs. For example required and optional Characteristics and possible values. Another thing is to write summary what you can achieve with what Service. |
Beta Was this translation helpful? Give feedback.
-
Both good ideas. I added these. They might be better off as two separate wiki pages, have one with the two tables (service and characteristics) then the other wiki page for examples. For now I'm just putting together some initial documentation. I've just added a start to the wiki page on this. I'm not sure how to upload my screenshots - I believe they'll need to be added to a folder in the github repo then linked in the wiki page, is this correct? Take a look here Feel free to edit, add, rearrange, or tell me what you think should be changed. I'll be working on adding more examples over the next few days/weeks. |
Beta Was this translation helpful? Give feedback.
-
|
Good starting point. Of course, it would be good to separate Servs and Chars into wiki pages. I'm not sure if hosting everything on one bridge is a good idea. Why?
Here is example how to add images. |
Beta Was this translation helpful? Give feedback.
-
|
Another idea. |
Beta Was this translation helpful? Give feedback.
-
|
By the way there is an outdated homekit document by apple for non-commercial use. If you found newest then please share. |
Beta Was this translation helpful? Give feedback.
-
|
I'll get things separated out into separate pages, I think I like the idea of separate pages for each accessory. Things like "switch" will be very simple while "irrigation controller" could be more complicated. As for putting everything in one bridge - I have been running like this for months. I can simply add/delete a homebridge-service node while not touching the rest of my nodes. For example I had a StatelessProgrammableSwitch last week that was acting up so I deleted it and added a new one with a different name. New one works great. I do see benefit in the future possibly for having a "production bridge" and a "testing bridge" - or one for switches and one for a camera. I will try to explain this better! I'm sure things will change and get more interesting once the multiple services -> one accessory is ready (e.g. adding battery service to a motion detector) Yes I used that homekit document to put this together. I don't have the newest version but I believe some/all of the information is available through an apple developer account. I've tried to go through it to learn more but it's way over my head. So at this point we will have the following pages:
The services should each have a table of required and optional characteristics. Also how to set characteristic properties so things show up properly in homekit, etc... It's a start though! |
Beta Was this translation helpful? Give feedback.
-
|
I think I'm getting this wiki thing figured out a little bit. For now I'm adding examples that I have used and I know work. I have several more that I've tested and will add them soon (fan, window covering, occupancy detector, smoke detector, stateless switch, and valve) Hopefully others come in to add their own examples. |
Beta Was this translation helpful? Give feedback.
-
|
Hello @crxporter, |
Beta Was this translation helpful? Give feedback.
-
|
@djiwondee thanks for examples. I think it would be good to standardise those pages. |
Beta Was this translation helpful? Give feedback.
-
|
@Shaquu as you may have recognized I just followed the given structure as of @crxporter assuming this is/will become the standard |
Beta Was this translation helpful? Give feedback.
-
|
@djiwondee I just adjusted your "Details" table on the CO2 detector to show the range of accepted values. A comment on that one - the copyable node doesn't look like it would be a "functional example" for a user to click inject nodes and see the device function in their Home app. I might suggest we add an inject node for both Also - for optional/required characteristics the homekit protocol document (linked above from @Shaquu) shows only "Carbon Dioxide Detected" for "required" characteristics while others are optional. This would mean the sensor is, at a minimum, true/false carbon detected - and optionally shows current and peak levels. I'm going to update your table accordingly - please correct me if I'm mistaken! Check out the Dimmable Light example to see how I used the random. PS- thanks for the contribution! Sometime I need to get myself some air quality sensors... |
Beta Was this translation helpful? Give feedback.
-
|
Just went back to the homekit spec - "Peak Level" is not an alarm threshold but instead the maximum level detected - this number would be saved so you can go back and see "how bad did it get" ... You could potentially have a reset button in nodered or program so it's a rolling 24-hour maximum or something. But it is NOT an alarm threshold. The alarm is set by "CarbonDioxideDetected" With this information, I'm going to update the tables again real quick. Should initial levels sent by characteristic property should be 0 so the user doesn't see levels from the start? |
Beta Was this translation helpful? Give feedback.
-
|
Hello @crxporter, have applied some changes. You are right with the behavior of the peak level characteristics. I have also embedded a new flow and screen shot. Instead of using random values for injection I just chose two inject node to demonstrate the behavior of the peak level alerting as given by the Node-Red flow programming. I struggle a little bit with the "Required" vs "Optional" characteristics. It doesn't matter how to set up this for the CO2 sensor HomeKit service. The functionality is always given and the automatically updated in Home.App. However to achieve an meaningful setup, I set only the CarbonDioxideLevel to required and have added all used characteristics of my example in the characteristic properties of the node-red node. |
Beta Was this translation helpful? Give feedback.
-
|
Looking at your newest table - the "CarbonDioxideLevel" is not required. The "CarbonDioxideDetected" is required. This makes sense because the true/false detected is the only required item to know if there's an alarm. The current and peak levels are just bonus informations. I like your new example! That will let people see the alarm or non alarm. While you were doing that edit I came up with this. It adds a "reset" button to bring the peak level back to 0 PPM - for after an alarm event to kind of set an "all clear"...
It takes an "inject" button - picks a random value between 0 and 100,000 (range of accepted values) then sends it as current level. There's also a function that checks whether that level is higher than the previous - and whether it's an alarm (I set the alarm level to be over 10,000). If it's an alarm it sends the alarm to HomeKit for 30 seconds. Additionally there is a button to reset the peak level. Edit: tweaked the function node a little. Edit 2: changed again. Added another random so it can be sent "alarm level" or "non alarm level"
Copyable: Note - we don't necessarily have to change your example, I think it is pretty good as it is. I've been trying to learn more about this because the carbon monoxide detector will eventually use nearly the same code. I plan to let you do the "Full Featured" example on CO2 - but am getting ready to do the examples for CO. Edit 3: just added Carbon Monoxide |
Beta Was this translation helpful? Give feedback.
-
|
@Shaquu I don't know what is the best idea regarding the bridge... I have read on several forums, that the hard maximum for a bridge is 150 accessory (but due to hardware limitations - like RPi), you will experience problems much before that limit. Also if you can, please update the README page to include a link to the Wiki pages. If we can solve these things out, then this will become one of the many (unrealiable) HomeKit controllers. |
Beta Was this translation helpful? Give feedback.
-
Yes. Always yes. Whatever example you or anyone else is willing to take the time to document in the wiki is welcome and encouraged! |
Beta Was this translation helpful? Give feedback.
-
|
This is my Sample, does it fit in ? https://github.com/NRCHKB/node-red-contrib-homekit-bridged/wiki/Sample-Sonoff-Dimmer
|
Beta Was this translation helpful? Give feedback.
-
|
@NorthernMan54 - since this is a "dimmer" I would recommend adding it to the light bulb wiki page found here While you're there, consider changing the name of that page from "Light Bulb" to "Light Bulb/Dimmer" since dimmers are more comprehensive than just light bulbs. The way the wiki has been set up so far is to have each example under its item type. If we want to add an examples section somewhere else than we ought to rearrange the whole wiki to be set up as such. Edit: PS- Thanks for the contribution! |
Beta Was this translation helpful? Give feedback.
-
|
@crxporter I moved things around, take a look |
Beta Was this translation helpful? Give feedback.
-
|
I wrote this, http://auto.caitken.com/posts/2018/09/09/nodered-homekit-reference, last year for the original node-red homekit plugin. It documents Services and their required or optional Characteristics. I'd be happy to contribute the missing docs here? |
Beta Was this translation helpful? Give feedback.
-
|
I have edited Example Switch page.
So main purpose of my change was to allow user who reads a page to immediately see how it will look and behave. I recently caught myself looking through wiki to see which Service would allow me to make computer desk automation (to move desk up and down) and found out that screenshots and video would be usefull. Anyway, @crxporter and others please comment what do you think about the change and what would be tweaked. Switch is smallest Service so it is easier to test changes here. @caitken-com are you still planning to contribute to our wiki? |
Beta Was this translation helpful? Give feedback.
-
|
@Shaquu Nice work on the Switch page, very useful! I've updated the few pages that were missing the required and optional Characteristics; BatteryService, CameraRTPStreamManagement, ContactSensor, Door, Doorbell, GarageDoorOpener, HumiditySensor, LeakSensor, LightSensor, LockMechanism, Microphone, MotionSensor, Outlet, Speaker, SmokeSensor. Can expand on these as you have with the switch page, but I thought if at least the characteristics were documented users would have a starting point :) |
Beta Was this translation helpful? Give feedback.
-
|
It would be very helpful to replace the readme:
With: View the Wiki for list of required and optional Characteristics you can address per Accessory. |
Beta Was this translation helpful? Give feedback.
-
|
@caitken-com maybe instead replacing change it to something like (just sketch):
|
Beta Was this translation helpful? Give feedback.
-
|
@NRCHKB/documentation |
Beta Was this translation helpful? Give feedback.
-
|
I'm playing around a little bit with
My camera is connected to a raspi using motion for the streaming and this works quite well: Since motion allows various movie codecs I would like to know what the parameters values especially for
I saw a couple of threads about camera here in this repo. May be it was already mentioned somewhere else. So I would be happy of you could point me to the right post. Thanks! |
Beta Was this translation helpful? Give feedback.
-
|
@djiwondee please read story in #16 And here you can find some configuration tips. |
Beta Was this translation helpful? Give feedback.
-
|
Hello all. I discovered something interesting today. For a long time I've been scaling insteon values (brightness range 1-255) over to homekit values (brightness 0-100) and back. I learned today that if your characteristic properties looks like: {
"Brightness": {
"maxValue":255
}
}That homekit will use the 0-255 values. Similarly for my new zwave devices, the scale is 0-99 where 0 is off and 99 is full bright. Properties look like: {
"Brightness": {
"maxValue":99
}
}This also works for minvalue. Hopefully this will be useful to someone, my next examples in the wiki page will include this once I've got things settled on my zwave setup. |
Beta Was this translation helpful? Give feedback.
-
|
Interesting info regarding rich notifications and doorbell service: while putting just a doorbell in a room with a camera and other devices (locks, lights) doesn't product rich notifications any more, combining just the camera and doorbell into one accessory does result in rich notifications also including locks and lights. That is: doorbell alone -- notification is only that it rang; doorbell and camera in same accessory -- notification includes camera feed and lock/light controls in the same room |
Beta Was this translation helpful? Give feedback.
-
|
Thank you all for the help getting the docs to where they are today!! Please continue contributing wherever you are able! I'm closing this one down in favor of the new demo setup, #301 - please check it out and share ideas! |
Beta Was this translation helpful? Give feedback.
-
I've been thinking of ways I can contribute to this project - and I'm wondering if there would be much benefit to have a place to keep examples.
I'm thinking to create some example flows to share either in the docs or on the wiki page. These would include an example of each service type with inject and debug nodes on either side so users can easily see how things can be put together and what the format is for things.
I know that sending {"foo":"bar"} will list options in the debug but it's not always straightforward from there to see how things actually work. Additionally there is little information on how to use characteristic properties. Eventually this will likely be helpful for the coming combined services (I.e. adding battery level to another item).
A quick example of what I'm thinking is here - I would include a screenshot and a copyable flow for the user to then adapt to their setup.
I don't know about everyone else but something like this would have gotten me going much quicker when I first picked up this node.
Any input about where to put this documentation or what could be added will be helpful, I'll be working on it in the coming weeks. We can use this issue as a discussion of how things should look.
Beta Was this translation helpful? Give feedback.
All reactions