https://github.com/csutorasa/icon-metrics
NGBS iCON smart home control system metrics reader
https://github.com/csutorasa/icon-metrics
Last synced: about 1 year ago
JSON representation
NGBS iCON smart home control system metrics reader
- Host: GitHub
- URL: https://github.com/csutorasa/icon-metrics
- Owner: csutorasa
- License: mit
- Created: 2021-03-29T18:20:55.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-04T19:23:13.000Z (about 1 year ago)
- Last Synced: 2025-03-29T16:34:24.320Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 204 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# iCON-metrics
This is an command line application which reads data from [NGBS iCON smart home control systems](https://www.ngbsh.hu/en/icon.html).
The data is processed and is exposed to be scraped from [prometheus](https://prometheus.io/).
Data from prometheus can be display in different ways, but [grafana](https://grafana.com/) is recommended.
## Read data
Data is read from the control system(s).
To define the control systems to be scraped, [config file](config.yml) needs to be updated.
```yaml
port: 8080 # port to run on (defaults to 80)
devices:
- url: http://192.168.1.10 # device address
sysid: '123123123123' # device ID (printed on the controller)
password: '123123123123' # password (defaults to sysid if empty)
delay: 60 # delay in seconds between reads (defaults to 15)
- url: http://192.168.1.11 # device address
sysid: '321321321321' # device ID (printed on the controller)
```
Config.yml validation can be done via the [schema](config.schema.json).
For further configuration options use the [schema](config.schema.json) to explore and validate your config file.
## Build on linux
- Install latest version of [go](https://go.dev/).
- Clone this repository `git clone https://github.com/csutorasa/icon-metrics.git`.
- Build the applciation `go build`.
- Depending on the operating system:
- Debian or debian based - Run the [deb package builder](packaging/pkg-debian) and install it, `packaging/pkg-deb && dkpg -i packaging/icon-metrics-*.deb`.
- Linux - Run the [installer](packaging/pkg-install) `sudo packaging/pkg-install`.
- Windows or MacOS - Run or schedule start the application.
## Docker image
Create your config.yml and run the command below
```bash
docker run -d -v /path/to/your/config.yml:/app/config.yml -p8080:8080 csutorasa/icon-metrics:latest
```
If you do not want use 8080 port then use `-p${YOUR_PORT}:8080`.
## Metrics
```mermaid
graph TD
A1[iCON thermostat controller 1] -->|Reads values| B[iCON-metrics]
A2[iCON thermostat controller 2] -->|Reads values| B[iCON-metrics]
A3[iCON thermostat controller 3] -->|Reads values| B[iCON-metrics]
B -->|Reports metrics| C[(Prometheus)]
C -->|Provides data| D[Grafana]
D --> E[Browser]
```
```mermaid
sequenceDiagram
participant it as iCON thermostat controller
participant im as iCON-metrics
participant p as prometheus
loop forever
im->>+it : login
it->>-im : login success
loop until logged out
im->>+it : read values
it->>-im : thermostat values
p->>+im : read metrics
im->>-p : thermostat values
end
end
```
### Prometheus scraper
Metrics are hosted in [prometheus](https://prometheus.io/) format.
The http server port can be configured in the [config file](config.yml).
```yaml
port: 8080
```
You need to extend the prometheus config (prometheus.yml) to scrape this application.
```yaml
scrape_configs:
# Other scrape configs can be here
- job_name: 'icon-metrics'
static_configs:
- targets: ['localhost:8080']
```
### Metrics reporting
Most metrics can be disabled from the configuaration separately for each device in the [config file](config.yml).
Available metrics:
| Metric | Scope | Type | Description | Enable configuration flag |
| ------------------------- | -------------- | ------- | --------------------------------------------------------- | ------------------------- |
| uptime | global | gauge | uptime in milliseconds | N/A |
| icon_controller_connected | per controller | gauge | 1 if the controller is ready to be read, 0 otherwise | controllerConnected |
| icon_http_client_seconds | per controller | summary | icon HTTP request durations in seconds | httpClient |
| icon_external_temperature | per controller | gauge | external temperature | externalTemperature |
| icon_water_temperature | per controller | gauge | cooling or heating water temperature | waterTemperature |
| icon_heating | per controller | gauge | 1 if the controller is set to heating mode, 0 otherwise | heating |
| icon_eco | per controller | gauge | 1 if the controller is in economy mode, 0 otherwise | eco |
| icon_room_connected | per room | gauge | 1 if the room is connected to the controller, 0 otherwise | roomConnected |
| icon_temperature | per room | gauge | room temperature | temperature |
| icon_relay_on | per room | gauge | 1 if the relay is open, 0 otherwise | relay |
| icon_humidity | per room | gauge | room humidity | humidity |
| icon_target_temperature | per room | gauge | room target temperature | targetTemperature |
| icon_dew_temperature | per room | gauge | room dew temperature | dewTemperature |
## Grafana dashboard
This data is designed to be displayed in a [grafana dashboard](https://grafana.com/docs/grafana/latest/dashboards/).
Example dashboards for the [system](grafana-iCON-system.json), [controllers](grafana-iCON-controllers.json) and the [rooms](grafana-iCON-rooms.json) are available to be [imported](https://grafana.com/docs/grafana/latest/dashboards/export-import/).
