# dbus-template

Venus OS D-Bus service template. Use this as a starting point for new services.

## Getting Started

1. Copy this directory: `cp -r _template/ dbus-your-service-name/`
2. Rename `dbus-template.py` to match your service (e.g. `your_service.py`)
3. Update `config.py` with your service name, product ID, and settings
4. Update `service/run` to point to your renamed main script
5. Update `install.sh`: set `SERVICE_NAME` and `MAIN_SCRIPT` variables
6. Update `build-package.sh`: set `PACKAGE_NAME` and the file copy list
7. Replace this README with your own documentation

## Files

| File | Purpose |
|------|---------|
| `dbus-template.py` | Main service with D-Bus registration boilerplate |
| `config.py` | Configuration constants (service name, product ID, timing) |
| `service/run` | daemontools entry point |
| `service/log/run` | multilog configuration |
| `install.sh` | Venus OS installation (velib symlink, service registration, rc.local) |
| `uninstall.sh` | Removes service symlink |
| `build-package.sh` | Creates a deployable .tar.gz package |

## D-Bus Paths

Update these for your service:

| Path | Type | Description |
|------|------|-------------|
| `/ProductName` | string | Service display name |
| `/Connected` | int | Connection status (0/1) |
| `/Settings/Template/Enabled` | int | Enable/disable via settings |

## Venus OS Best Practices

The template follows these [Venus OS wiki](https://github.com/victronenergy/venus/wiki) guidelines:

- **`register=False`** -- `VeDbusService` is created with `register=False`, paths are added, then `register()` is called to prevent race conditions with consumers.
- **`@exit_on_error`** -- Applied to the `GLib.timeout_add` callback so unhandled exceptions crash the process instead of silently dropping the callback.
- **`daemon=True`** -- Set on background threads so they don't prevent process exit.
- **multilog** -- Log size capped at `s25000 n4` (~100KB) to avoid filling the `/data` partition.

## Checklist

- [ ] Unique service name in `config.py` (`com.victronenergy.yourservice`)
- [ ] Unique product ID in `config.py` (check existing services to avoid conflicts)
- [ ] All file references updated in `service/run`, `install.sh`, `build-package.sh`
- [ ] Custom D-Bus paths added
- [ ] Settings paths updated
- [ ] `@exit_on_error` on all `GLib.timeout_add` callbacks
- [ ] Background threads use `daemon=True`
- [ ] README replaced with your own documentation