Setting Up Your Config.json file
(This is a work in progress!)
I need to add instructions on how to do this, but the following 3 images should be a good hint. "Old" manual instructions start below these images.
A good starting point to setting up the config.json file is the examples found at: https://github.com/jvmahon/homebridge-homeseer4/tree/master/config . There are two sample files there:
- "config.simple.json" - This is the simplest 'minimal' file for setting up devices. I generally recommend people start with this file (rename it to config.json). Devices are set up by adding them to group arrays as a comma-separated list of HomeSeer references. For example, if you had two lightbulbs with homeseer references 200, and 210 and two thermostat with root devices 128 and 1100 you would add them as shown below. NOTE: Thermostats are added using their HomeSeer 'root' device reference number, while other devices use the device's reference number directly, not the 'root' device.
"Fans": [],
"GaragedDoorOpeners": [],
"Lightbulbs": [200, 210],
"lightbulbs": [],
"Locks": [],
"Thermostats": [128, 1100],
"Outlets": [],
"Switches": [],
"Windows": [],
"WindowCoverings": [],
"CarbonDioxideSensors": [],
"CarbonMonoxideSensors": [],
"ContactSensors": [],
"HumiditySensors": [],
"LeakSensors": [],
"LightSensors": [],
"MotionSensors": [],
"OccupancySensors": [],
"SmokeSensors": [],
"TemperatureSensors": [],
"Valves": [],
"SecuritySystems": [],
- "config.complex.json" should be used by people who need to customize the settings of devices for unique circumstances. As with config.simple.json, the "complex" file gets renamed as config.json and placed in your homebridge directory. The config.complex.json also shows how devices can be added by detailing them individually as entries in the "accessories" rather. Adding devices using the "accessories" group method allows a much higher degree of customization of their parameters, including, e.g., setting particular on and off values used by bulbs, switches, and outlets as well as values used by various sensors. Section "G", below, gives more information on customization parameters.
In order to set up the config.json file needed to use this plugin, you will first need to set HomeSeer to display the Home Seer Device Reference numbers.
For HomeSeer 3: From the HomeSeer "Tools" menu, choose "Setup". Then choose the "Custom" tab and click the check box next to "Show Device Reference Number on Device Management Page (for developers)" setting. The device reference number will then show in the "Ref" column.
For HomeSeer 4: From the HomeSeer "Tools" menu, choose "Setup". Then choose the "Custom" tab and click the check box next to "Show Device Ref on Status Page" setting. The device reference number will then show on the Device's "Status/Graphics" page. In HomeSeer 4 it will be labeled the "ID" rather than "Ref". Note that for a device with multiple functions, there will be a different ID for each function.
Note: Be very careful how you set up this file! A common error is extra or missing commas. Note that the last item in the "Accessories" group should NOT have a comma after it. See the example files.
Though the example files have some commments in them (starting with two slashes //), you cannot have any in your final file!
It is very strongly recommended that after any change to your config.json file, you check it by pasting the comments into the JSON format checker found at: https://jsonlint.com/
can_dim - Previously, for dimmable / speed adjustable devices, a user would specify a "can_dim":true value in the accessories entry for Lightbulbs and Fans. This is no longer used!.
Garage door openers now only require that the "main" HomeSeer reference and obstruction sensor reference be specified. See example configuration files.
uuid_base - Generally speaking, you no longer need to specify this parameter for Accessories. The plugin will now automatically set it to the string "Ref" + the device reference number. The only time you need to manually set it is if you use the same HomeSeer reference for two or more Accessories (It is possible you could use the same HomeSeer reference number to, e.g., make a lock appear as both a lock and a switch, but other than these odd types of use cases, this should virtually never happen). You should continue to specify uuid_base for Events.
(Further clarification of this section is needed.)
"platform": "HomeSeer", // Required
"name": "HomeSeer", // Required
"host": "http://yourserver", // Required
"ASCIIPort":11000 // Optional - Defaults to 11000. This is the TCP/IP Port for ASCII control interface. Used for Instant Status. Must match setting on "Tools" -> "Setup" -> "Network" tab of HomeSeer.
"login":"default", // Required - your HomeSeer login specified on HomeSeer's Tools -> Setup -> Network page.
"password":"default", // Required - your HomeSeer password specified on HomeSeer's Tools -> Setup -> Network page.
Note that there is a new requirement to specify your HomeSeer login and password in your config.json file. If you do not do so, then"default", "default" will be used.
This section needs to be cleaned up! This is a listing of all the parameters that may be used when you set up devices in the "accessories" block of the config.json. Please refer to the config.complex.json file at https://github.com/jvmahon/Homebridge-HomeSeer4/tree/master/config for additional information.
| Parameter | Required | Used With | Description |
|---|---|---|---|
| name | Optional | All | Automatically set to the Homeseer room name + device name if not user-specified |
| ref | Mandatory | All | User selected. Generally set to the reference # of the primary HomeSeer device for the given "type". For Thermostats, this is the primary temperature sensor device. |
| uuid_base | Optional | All | User's generally don't have to set this unless you have the same homeseer reference number being used for more than one device. An example of when this might be done is shown here: https://github.com/jvmahon/Homebridge-HomeSeer4/wiki/Show-the-same-device-in-multiple-rooms. Usually automatically set to "Ref" + the reference # |
| batteryRef | Optional | All | Identifies the related 'battery' device, if any. Plugin can automatically determine this for Z-Wave devices. |
| batteryThreshold | Optional | All | User can select the battery threshold, if desired. |
| onValue | Optional | Lights, Fan, Outlet, Switches | User RARELY needs to set this. Generally, only set if your device turns on using a value other than 255. |
| offValue | Optional | Lights, Fan, Outlet, Switches | User RARELY needs to set this. Generally, only set if your device turns off using a value other than 0. |
| levels | Optional | Lights, Fan | User RARELY needs to set this. Used to set the number of levels used by a device supporting a percentage setting. Z-Wave has a quirk that it only supports 99 levels (0 - 99%) . Most other lighting / multilevel devices support 100 levels (0 - 100%) |
| colorTemperatureRef | Optional | Lightbulb | Set to HomeSeer device reference used to select color Temperature of a "white" bulb. Expressed in units of mirek. Apple iOS's Home application can set this to a value of 50-400 mirek. |
| offValues | Optional | Sensors | An ARRAY of values used for sensor devices. Should be set to include all possible values reported by HomeSeer for an "off" or "untriggered state". |
| tamperRef | Optional | Sensors | User selected. Generally set to the reference # of the a HomeSeer tamper device. May be used for some sensors |
| minCelsius | Optional | TemperatureSensor | minimum temperature that can be reported. Must be expressed in Celsius (even if HomeSeer is set to Fahrenheit) |
| maxCelsius | Optional | TemperatureSensor | maximum temperature that can be reported. Must be expressed in Celsius (even if HomeSeer is set to Fahrenheit) |
| lockValue | Optional | Lock | Value to command HomeSeer to lock door / reported when door is locked. |
| unlockValue | Optional | Lock | Value to command HomeSeer to unlock door / reported when door is unlocked. |
| doorSensorRef | Optional | Lock | Set to ref # of contact sensor indicating if door is open or closed. "doorSensorRef" doesn't do anything. In future versions of plugin, it may be used to inhibit door locking if the door isn't fully closed. |
| openValue | Optional | GarageDoorOpener | Value reported by HomeSeerwhen door is open |
| closedValue | Optional | GarageDoorOpener | Value reported by HomeSeerwhen door is open |
| openingValue | Optional | GarageDoorOpener | Value reported by HomeSeer when door is in the process of opening |
| closingValue | Optional | GarageDoorOpener | Value reported by HomeSeer when door is in the process of closing |
| stoppedValue | Optional | GarageDoorOpener | Value reported by HomeSeer when door has stopped moving, but is neither open or closed. |
| armStayValue | Optional | SecuritySystem | Value sent to HomeSeer to indicate the system should be armed, with 'people home' mode. |
| armAwayValue | Optional | SecuritySystem | Value sent to HomeSeer to indicate the system should be armed, with 'nobody home'. |
| armNightValue | Optional | SecuritySystem | Value sent to HomeSeer to indicate the system should be armed, 'night mode'. |
| disarmValue | Optional | SecuritySystem | Value sent to HomeSeer to indicate the system should be disarmed. |
| armedStayValues | Optional | SecuritySystem | Array of Values reporting system is armed, with people home mode. |
| armedAwayValues | Optional | SecuritySystem | Array of Values reporting system is armed, with nobody home. |
| armedNightValues | Optional | SecuritySystem | Array of Values reporting system is armed in home mode, night mode. |
| disarmedValues | Optional | SecuritySystem | Array of Values reporting system is disarmed. |
| alarmValues | Optional | SecuritySystem | Array of Values reporting system is currently in an alarm triggered state. |
| controlRef | Optional | Thermostat | Set to HomeSeer device by which you select the Off / Heat / Cool / Auto state. |
| stateRef | Optional | Thermostat | Set to HomeSeer device reporting the actually running state (Off / Heat / Cool). If there is no separate stateRef for your device, try setting this the same as controlRef (though that will likely show as the system always running in Heat or Cool). However, there must always be a device that corresponds to controlRef where you actually set the mode for your HVAC system! |
| heatingSetpointRef | Optional | Thermostat | Either "heatingSetpointRef" or "coolingSetpointRef" must be set (usually both are!) |
| coolingSetpointRef | Optional | Thermostat | Either "heatingSetpointRef" or "coolingSetpointRef" must be set (usually both are!) |
| humidityRef | Optional | Thermostat | optional. Set to HomeSeer device that provides a humidity report. |
| humidityTargetRef | Optional | Thermostat | Set to HomeSeer device that allows you to set humidity setpoint. |
| valveType | Optional | Valve | Valve type. 0 = Generic, 1 = Irrigation, 2 = Shower Head, 3 = Faucet. |
| openValve | Optional | Valve | Value sent to open the valve |
| closeValve | Optional | Valve | Value sent to close the valve |
| useTimer | Optional | Valve | Experimental - enables valve timer functionality. Set timer from devices "details" page. |
| minTime | Optional | Valve | Experimental - minimum time in Seconds when valve timer functionality is enabled. |