Edilkamin.js


This is a library for the Reverse Engineered "The Mind" Edilkamin API.
The Mind offers an app/API to remote control the Edilkamin pellet stoves.

Install

Using npm:

``sh
npm install edilkamin
`

Using yarn:

`sh
yarn add edilkamin
`

Usage

Basic usage:

`js
import { signIn, deviceInfo, setPowerOff } from "edilkamin";

const macAddress = "aabbccddeeff";
const token = await signIn(username, password);
console.log(await deviceInfo(token, macAddress));
console.log(await setPowerOff(token, macAddress));
`

For long-running applications, use getSession() to automatically refresh tokens:

`js
import { signIn, getSession, deviceInfo } from "edilkamin";

// Authenticate once
await signIn(username, password);

// Get current session (auto-refreshes if expired)
const token = await getSession();
console.log(await deviceInfo(token, macAddress));
`

Sessions persist for ~30 days without re-authentication. Call getSession() to retrieve fresh tokens as needed.

It's also possible to change the default backend URL:

`js
import { signIn, configure } from "edilkamin";

const baseUrl = "https://my-proxy.com/";
const { deviceInfo, setPower } = configure(baseUrl);
console.log(await deviceInfo(token, macAddress));
console.log(await setPower(token, macAddress, 0));
`

CLI

The library includes a CLI tool that is useful for debugging.

`sh


First time: provide credentials to authenticate

yarn cli deviceInfo --mac $MAC --username $USERNAME --password $PASSWORD

Subsequent calls: session persists, credentials optional

yarn cli deviceInfo --mac $MAC

Clear stored session

yarn cli logout
`

Or with npx once the library is installed:

`sh
npx edilkamin deviceInfo --mac $MAC --username $USERNAME --password $PASSWORD
`

The CLI stores session data in ~/.edilkamin/session.json and automatically refreshes tokens when needed. Sessions remain valid for ~30 days.

API Versions

This library supports both the new and legacy Edilkamin API endpoints.

$3

`sh


New API (default)

yarn cli deviceInfo --mac $MAC --username $USERNAME --password $PASSWORD

Legacy API

yarn cli deviceInfo --mac $MAC --username $USERNAME --password $PASSWORD --legacy
`

$3

`js
import { configure, signIn, OLD_API_URL, NEW_API_URL } from "edilkamin";

// New API (default)
const token = await signIn(username, password);
const api = configure();

// Legacy API
const legacyToken = await signIn(username, password, true);
const legacyApi = configure(OLD_API_URL);
`

> Note: The legacy API uses AWS API Gateway and may be deprecated in the future.

Bluetooth Device Discovery

For automatic device discovery in web browsers, use the edilkamin/bluetooth subpath export.

$3

`javascript
import { scanForDevices } from "edilkamin/bluetooth";
import { deviceInfo, signIn } from "edilkamin";

// Scan for nearby stoves (requires user gesture)
const devices = await scanForDevices();
const { wifiMac } = devices[0];

// Use discovered MAC for API calls
const token = await signIn(username, password);
const info = await deviceInfo(token, wifiMac);
`

$3

The core library includes a helper to convert BLE MAC to WiFi MAC:

`javascript
import { bleToWifiMac } from "edilkamin";

// BLE MAC from Bluetooth scan
const bleMac = "A8:03:2A:FE:D5:0A";

// WiFi MAC for API calls (BLE - 2)
const wifiMac = bleToWifiMac(bleMac); // "a8032afed508"
`

Motivations

- providing an open source web alternative
to the proprietary mobile app
- improving the interoperability (Nest, HomeAssistant...)

Device Control Methods

The library provides comprehensive control over Edilkamin stoves:

$3

`js
setPowerOn(token, mac); // Turn on
setPowerOff(token, mac); // Turn off
setPower(token, mac, 1); // 1=on, 0=off
getPower(token, mac); // Returns boolean
setPowerLevel(token, mac, 3); // Set power level (1-5)
getPowerLevel(token, mac); // Returns 1-5
`

$3

`js
setFan1Speed(token, mac, 3); // Set fan 1 speed (0-5)
setFan2Speed(token, mac, 3); // Set fan 2 speed (0-5)
setFan3Speed(token, mac, 3); // Set fan 3 speed (0-5)
getFan1Speed(token, mac); // Get fan 1 speed
getFan2Speed(token, mac); // Get fan 2 speed
getFan3Speed(token, mac); // Get fan 3 speed
`

$3

`js
setAirkare(token, mac, true); // Enable/disable air quality mode
setRelax(token, mac, true); // Enable/disable comfort mode
setStandby(token, mac, true); // Enable/disable standby mode
getStandby(token, mac); // Get standby status
setStandbyTime(token, mac, 30); // Set standby timer (minutes)
getStandbyTime(token, mac); // Get standby timer
setAuto(token, mac, true); // Enable/disable auto mode
getAuto(token, mac); // Get auto mode status
`

$3

`js
setTargetTemperature(token, mac, 22); // Set zone 1 temperature
getTargetTemperature(token, mac); // Get zone 1 target
getEnvironmentTemperature(token, mac); // Get ambient temperature
setEnvironment2Temperature(token, mac, 20); // Set zone 2 temperature
getEnvironment2Temperature(token, mac); // Get zone 2 target
setEnvironment3Temperature(token, mac, 18); // Set zone 3 temperature
getEnvironment3Temperature(token, mac); // Get zone 3 target
`

$3

The library supports weekly scheduling through Chrono Mode:

`js
import {
setChronoMode,
setChronoComfortTemperature,
setChronoEconomyTemperature,
setChronoTemperatureRanges,
createWorkWeekSchedule,
Day,
ChronoTemperatureSlot,
} from "edilkamin";

// Configure temperature targets
await setChronoComfortTemperature(token, mac, 22); // Comfort = 22°C
await setChronoEconomyTemperature(token, mac, 18); // Economy = 18°C

// Create and apply a schedule
const schedule = createWorkWeekSchedule({
morningStart: 6,
morningEnd: 9,
eveningStart: 17,
eveningEnd: 22,
});
await setChronoTemperatureRanges(token, mac, schedule);

// Enable chrono mode
await setChronoMode(token, mac, true);
`

Schedule arrays are 336 integers (7 days × 48 half-hour slots):

- 0 = OFF (stove off)
- 1 = Economy (target economy temperature)
- 2 = Comfort (target comfort temperature)

Helper functions for building schedules:

- createEmptySchedule() - Create an all-OFF schedule
- createWorkWeekSchedule(options) - Create a typical work-week pattern
- setScheduleRange(schedule, day, startHour, endHour, value) - Set a time range
- setWeekdayRange(schedule, startHour, endHour, value) - Set Mon-Fri
- setWeekendRange(schedule, startHour, endHour, value) - Set Sat-Sun
- timeToIndex(day, hour, minute) - Convert time to array index
- indexToTime(index) - Convert array index to time

$3

`js
import { setEasyTimer, getEasyTimer } from "edilkamin";

// Set auto-shutoff timer (minutes)
await setEasyTimer(token, mac, 120); // Turn off in 2 hours

// Check timer status
const timer = await getEasyTimer(token, mac);
console.log(timer); // { active: true, time: 120 }

// Disable timer
await setEasyTimer(token, mac, 0);
`

Roadmap

- [x] AWS Amplify/ Cognito authentication
- [x] unauthenticated endpoint call
- [x] authenticated endpoint call
- [ ] ~list stoves~
- [x] turn stove on/off
- [x] set temperature
- [x] power level control
- [x] fan speed control
- [x] operating modes (Airkare, Relax, Standby, Auto)
- [x] multi-zone temperature control
- [x] scheduling (Chrono Mode, Easy Timer)

Limitations

- No server-side device listing: The API doesn't provide an endpoint to list stoves associated to a user.
- Bluetooth discovery available: Use edilkamin/bluetooth for web browser device discovery, similar to the official app.
- Manual MAC entry fallback: For unsupported browsers or CLI, users can find the BLE MAC with different means and use bleToWifiMac()` to calculate the WiFi MAC for API calls.