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:

npm install edilkamin

Using yarn:

yarn add edilkamin

Usage

Basic usage:

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:

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:

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.

# 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:

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.

CLI Usage

# New API (default)
yarn cli deviceInfo --mac $MAC --username $USERNAME --password $PASSWORD

# Legacy API
yarn cli deviceInfo --mac $MAC --username $USERNAME --password $PASSWORD --legacy

Library Usage

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.

Quick Example (Web)

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);

MAC Address Helper

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

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:

Power Control

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

Fan Speed

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

Operating Modes

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

Temperature Control

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

Scheduling (Chrono Mode)

The library supports weekly scheduling through Chrono Mode:

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

Easy Timer

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

• AWS Amplify/ Cognito authentication
• unauthenticated endpoint call
• authenticated endpoint call
• list stoves
• turn stove on/off
• set temperature
• power level control
• fan speed control
• operating modes (Airkare, Relax, Standby, Auto)
• multi-zone temperature control
• 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.