# VE.Direct-notify

Welcome to VE.Direct-notfiy. A customisable notification service using unified push providers like ntfy.  
A PHP installation with the SQLite3-module activated and a network connection to your preferred notification service is needed to run the program. It is developed, tested and verified with PHP version 8.5.

## Configuration

VE.Direct-notify needs some configuration settings to work properly. These are collected in the JSON-formatted file config.json in VE.Direct-notify's root directory.  
The file is structured by directives controlling the various aspects of the programm:

### service

In this directive you define the notification service to use. VE.Direct-notify is tested and proofed working with the OpenSource notification service ntfy.  
The topic URL to use is derived from the parameters url and topic combined. the parameter url is to be given *without a trailing slash*.  
VE.Direct-notify supports conneting to notification services with and without authentication. Authentication can be by Username/Password or Authentication Token.  
  
example without authentication:
```
"service": {
    "url": "https://ntfy.yourdomain.com",
    "topic": "yourTopicName"
}
```


examaple with authentication using a username and password:  
```
"service": {
    "url": "https://ntfy.yourdomain.com",
    "username": "yourUserName",
    "password": "yourComplexPassword",
    "topic": "yourTopicName"
}
```

example with authentication using an authentication token:  
```
"service": {
    "url": "https://ntfy.yourdomain.com",
    "auth_token": "tk_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789",
    "topic": "yourTopicName"
}
```

### database 
In this directive the path to the SQLite-database to be used is defined. Usually, that will be the same as your VE.Direct-Text-Reader instance is using.  
The path can be absolute or relative to the VE.Direct-notify root directory.  
example:  
`"database": "/path/to/your/VEDirect.db"`

### monitors

The monitors represent the actual parameters to be checked by VE.Direct-notfy as well as the corresponding test conditions to each parameter.  
There can be an unlimitted number of parameters to monitor defined. All monitors are collected in the directive "monitors" as an array of objects containing the actual parameter(s) to monitor and the corresponding test conditions.  
example:  
```
"monitors": [
    {
        "parameter": "ERR",
        "error": ["gt", 0]
    }
]
```

#### test conditions

Test conditions can be defined as warnings or errors or both as object elements with an array containing 2 elements. The first one defines how the value shall be interpreted (see table below), the second is the value to test against.  
example: `"error": ["gt", 0]`

| value | Description                          |
| ----: | :----------------------------------- |
| e     | equal to given value                 |
| gt    | greater than given value             |
| gte   | greater than or equal to given value |
| lt    | lower than given value               |
| lte   | lower than or equal to given value   |
| ne    | not equal to given valeu             |
table of test conditions

### example config.json

```
{
    "service": {
        "url": "https://ntfy.example.com",
        "username": "",
        "password": "",
        "auth_token": "tk_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789",
        "topic": "MakeThisRandomOrComplexWithoutAuthentication"
    },
    "monitors": [
        {
            "parameter": "ERR",
            "error": ["gt", 0]
        },
        {
            "parameter": "V",
            "warning": ["lt", 11.5],
            "error": ["lte", 10.5]
        }
    ],
    "database": "/path/to/your/VE.Direct.db"
}
```

## Run the program

Once the configuration is set up properly, the programm can be run by:
```
$ cd /path/to/your/VE.Direct-ntfy-instance
$ php worker.php
```

Once tested successfully, it can be set up as a cron-job:
`$ crontab -e`

In the cron table fill in a line like this:
`0 * * * * php /path/to/your/VE.Direct-ntfy-instance/worker.php`

## Troubleshooting

## Contributing
VE.Direct-notify is an OpenSource project and we greatly appreciate any kind of support.  
For more details check CONTRIBUTING.md

## More VE.Direct tools
All our tools to interact with devices equipped with a VE Direct protocol compatible communictaion port can be found on our [git-server](https://git.schauaus.at/VE-Tools).