RAMSES ESPDevelopment
Contributing to the app, or adapting it yourself.
Getting started
You need Node.js 22, the Homey CLI and, for homey app run, Docker.
npm install| Command | What it does |
|---|---|
npm test | Tests only |
npm run check | Lint, type check, tests with coverage and manifest validation, exactly what CI runs |
npm run lint:fix | Fix lint errors automatically |
homey app run | Run the app on your Homey temporarily, with live logs |
homey app install | Install the app on your Homey permanently |
CI requires at least 85 % lines, 80 % branches and 85 % functions coverage over lib/.
Structure
The code is organised in layers. Everything below lib/homey runs under plain node --test, without Homey.
lib/
ramses/ protocol: Packet, decoders per code, commands, brand schemes, BusScanner, binding
mqtt/ connection: BrokerConfig, GatewayConnection, BrokerProbe
domain/ models: Gateway, FanUnit, Remote, ClimateSensor, VirtualSensor, events
homey/ adapters: GatewayRegistry, capabilities, flow cards, pairing, web API
drivers/ thin Homey drivers and devices
settings/ the bus view
widgets/ the dashboard widgetDependencies (MQTT connect, clock, timers, send function) are injected. That way the tests drive the whole
chain with fakes, from an MQTT message to a flow trigger.
A new brand or a new code
- Brand: add a
FanSchemeinlib/ramses/FanScheme.jsand a value to the Brand dropdown indrivers/fan/driver.settings.compose.json. - Message code: add a decoder in
lib/ramses/decoders.jsand, if it yields a new reading, a binding inlib/homey/ReadingCapabilities.js. - Write a test with a real frame from the bus.
Translations
The app is bilingual (English and Dutch). Texts are in locales/en.json and locales/nl.json, and in the
*.compose.json files. Homey placeholders are __id__, not {{id}}.
This documentation
The site lives in website/ and is built with Fumadocs (Next.js, static export). The
English pages are in website/content/docs/en/, the Dutch ones in website/content/docs/nl/, under the same file
names so the language switcher keeps you on the same page. The order of the sidebar is in each folder's
meta.json; the landing page is website/app/[lang]/(home)/page.tsx. View it locally:
cd website
npm install
npm run dev # http://localhost:3000/en/
npm run build # static export to out/| In a page | What it gives |
|---|---|
<Callout type="idea"> / "info" / "warn" / "error" | A tip, background, note or warning box |
<Mermaid chart={...} /> | A diagram that follows light and dark mode |
<DeviceImage device="gateway" alt="..." /> | A device illustration next to the text |
<DeviceIcon device="remote" /> | A small device illustration, for tables |
[label](./gateway.mdx#anchor) | A link to another page in the same language |
Every push to main that touches website/ builds the site and publishes it to the gh-pages branch
(.github/workflows/docs.yml). GitHub Pages serves that branch: Settings → Pages → Deploy from a branch →
gh-pages / / (root). The old Jekyll URLs redirect to the new pages.