46 lines
2.8 KiB
Markdown
46 lines
2.8 KiB
Markdown
# Agent Instructions
|
|
|
|
Welcome to the nymea EV-Dash experience plugin repository. This project ships a Qt-based experience plugin together with a small
|
|
HTML dashboard that visualises EV charger information exposed by nymea. The following notes summarise the most important pieces
|
|
you will touch while working on tasks in this repository.
|
|
|
|
## Purpose
|
|
- Deliver a secure, brandable dashboard that shows the status of configured EV chargers, their live data and actions.
|
|
- All browser interactions flow through a nymea web server resource that authenticates users and distributes data via WebSocket
|
|
push events.
|
|
|
|
## Repository Structure
|
|
- `plugin/`
|
|
- Contains the Qt/C++ implementation of the experience plugin.
|
|
- `EvDashWebServerResource` is responsible for HTTP handling under `/evdash`, including REST endpoints such as the login flow and
|
|
serving the compiled dashboard assets from `dashboard.qrc`.
|
|
- `EvDashEngine` runs the WebSocket server, receives JSON requests with `{ requestId, action, payload }`, authenticates clients via
|
|
session tokens and pushes live updates.
|
|
- `EvDashJsonHandler` defines the JSON-RPC schema for nymea integration (keep new actions consistent with this handler).
|
|
- `dashboard/`
|
|
- Browser-based UI written in HTML and vanilla JavaScript (`index.html`, `app.js`). The files are bundled into the plugin through
|
|
`dashboard.qrc`.
|
|
- Use CSS variables for branding (primary/secondary/accent colours, icons) so the dashboard can be themed easily.
|
|
|
|
## Implementation Guidelines
|
|
- Maintain the request/response contract documented in the repository README and API discussions:
|
|
```json
|
|
{ "requestId": "uuid", "action": "ActionName", "payload": { } }
|
|
```
|
|
Every response must echo the `requestId`, set `success` and either contain `payload` or an `error` string.
|
|
- The WebSocket connection stays closed for unauthenticated clients. They must send an `authenticate` action with a valid login
|
|
token obtained via `POST /evdash/api/login`. Reject subsequent requests until the token is validated.
|
|
- When adding UI behaviour, ensure the login overlay is shown before establishing a WebSocket connection and that connection status
|
|
is clearly visible for operators.
|
|
|
|
## Coding Style
|
|
- C++/Qt: follow Qt conventions (camelCase, `m_` member prefixes, grouped/alphabetised includes, Qt containers, Qt logging macros).
|
|
- JavaScript: prefer small helper functions, avoid external dependencies, keep DOM selectors at the top of the file, and document
|
|
any public methods intended for use from the developer console.
|
|
|
|
## Workflow & Testing
|
|
- Keep commits focused and group related changes across frontend/backend in the same patch where it improves traceability.
|
|
- Mention any manual or automated verification steps in commit messages and PR summaries. If tests are unavailable, explain why.
|
|
|
|
Thank you for contributing!
|