lamarzocco

La Marzocco espresso makineleri icin Node.js Cloud API istemcisi. pylamarzocco kutuphanesinin JavaScript portudur.

Desteklenen makineler: Linea Mini, Linea Micra, Linea Mini R, GS3, GS3 MP, GS3 AV

Kurulum

npm install

Node.js >= 18 gereklidir (built-in fetch ve crypto kullanilir).

Hizli Baslangic

import fs from 'node:fs';
import crypto from 'node:crypto';
import {
  generateInstallationKey,
  InstallationKey,
  LaMarzoccoCloudClient,
  LaMarzoccoMachine,
} from './src/index.js';

// 1) Installation key olustur veya dosyadan yukle
const KEY_FILE = '.lamarzocco-key.json';
let key, needsRegistration = false;

if (fs.existsSync(KEY_FILE)) {
  key = InstallationKey.fromJSON(JSON.parse(fs.readFileSync(KEY_FILE, 'utf-8')));
} else {
  key = generateInstallationKey(crypto.randomUUID());
  fs.writeFileSync(KEY_FILE, JSON.stringify(key.toJSON(), null, 2));
  needsRegistration = true;
}

// 2) Client olustur
const client = new LaMarzoccoCloudClient({
  username: '[email protected]',
  password: 'sifre',
  installationKey: key,
});

// 3) Sadece ilk seferde kayit et
if (needsRegistration) {
  await client.registerClient();
}

// 4) Makineyi bul ve kullan
const things = await client.listThings();
const machine = new LaMarzoccoMachine(things[0].serialNumber, client);
await machine.getDashboard();

console.log(machine.dashboard.config);

ONEMLI: generateInstallationKey() her cagrildiginda yeni bir ECDSA anahtar cifti olusturur. API sunucusu her installation ID icin sadece bir anahtar kabul eder. Bu yuzden key'i dosyaya kaydedip sonraki calistirmalarda oradan yukleyin. Key dosyasini kaybederseniz yeni bir UUID ile yeni key olusturun.

API Referansi

Baglanti ve Kimlik Dogrulama

generateInstallationKey(installationId)

Yeni bir ECDSA P-256 anahtar cifti ve 32-byte secret olusturur.

import { generateInstallationKey } from './src/index.js';

const key = generateInstallationKey('benzersiz-uuid');
// key.installationId  -> 'benzersiz-uuid'
// key.secret          -> Buffer (32 byte)
// key.publicKeyB64    -> Base64 string

InstallationKey.toJSON() / InstallationKey.fromJSON(obj)

Key'i JSON'a cevirip geri yukler (dosyada saklama icin).

// Kaydet
fs.writeFileSync('key.json', JSON.stringify(key.toJSON(), null, 2));

// Yukle
const loaded = InstallationKey.fromJSON(JSON.parse(fs.readFileSync('key.json', 'utf-8')));

new LaMarzoccoCloudClient({ username, password, installationKey })

Cloud API istemcisi olusturur. Otomatik token yonetimi yapar.

const client = new LaMarzoccoCloudClient({
  username: '[email protected]',
  password: 'sifre',
  installationKey: key,
});

client.registerClient() -> Promise<boolean>

Ilk baglantida istemciyi API'ye kayit eder. true doner basariliysa, false zaten kayitliysa.

const registered = await client.registerClient();

Cihaz Bilgileri

client.listThings() -> Promise<Array>

Hesaba kayitli tum cihazlari listeler.

const things = await client.listThings();
// [
//   {
//     serialNumber: 'LM025448',
//     type: 'CoffeeMachine',
//     name: 'LM025448',
//     modelCode: 'LINEAMINI',
//     modelName: 'Linea Mini',
//     connected: true,
//     connectionDate: Date,
//     imageUrl: 'https://...',
//     bleAuthToken: '...',
//     ...
//   }
// ]

machine.getDashboard() -> Promise<Object>

Makinenin dashboard verilerini (widget'lar) ceker. Sonuc hem doner hem machine.dashboard'a kaydedilir.

const dashboard = await machine.getDashboard();

// Makine durumu
dashboard.config['CMMachineStatus']
// { status: 'PoweredOn', mode: 'BrewingMode', availableModes: [...], nextStatus: null }

// Kahve kazani
dashboard.config['CMCoffeeBoiler']
// { status: 'Ready', enabled: true, targetTemperature: 93, targetTemperatureMin: 80, ... }

// Buhar kazani (Micra/Mini R)
dashboard.config['CMSteamBoilerLevel']
// { status: 'Ready', enabled: true, targetLevel: 'Level2', ... }

// Buhar kazani (GS3/Mini)
dashboard.config['CMSteamBoilerTemperature']
// { status: 'Ready', enabled: true, targetTemperature: 128, ... }

// Su durumu
dashboard.config['CMNoWater']
// { allarm: false }

// Backflush durumu
dashboard.config['CMBackFlush']
// { status: 'Off', lastCleaningStartTime: Date|null }

// Terazi
dashboard.config['ThingScale']
// { name: '...', connected: true, batteryLevel: 85, calibrationRequired: false }

machine.getSettings() -> Promise<Object>

Makine ayarlarini (firmware, WiFi, vb.) ceker.

const settings = await machine.getSettings();
// settings.wifiSsid         -> 'AgimYok'
// settings.wifiRssi         -> -45
// settings.isPlumbedIn      -> false
// settings.firmwares.Machine -> { type: 'Machine', buildVersion: '1.40', status: 'Updated', ... }
// settings.firmwares.Gateway -> { type: 'Gateway', buildVersion: '2.20', ... }

machine.getStatistics() -> Promise<Object>

Genel istatistikleri ceker.

const stats = await machine.getStatistics();
// stats.widgets -> { ... widget verileri ... }

machine.getSchedule() -> Promise<Object>

Zamanlama ayarlarini ceker.

const schedule = await machine.getSchedule();
// schedule.smartWakeUpSleep.smartStandByEnabled   -> true
// schedule.smartWakeUpSleep.smartStandByMinutes   -> 30
// schedule.smartWakeUpSleep.smartStandByAfter     -> 'LastBrewing'
// schedule.smartWakeUpSleep.schedules             -> [{ id, enabled, onTimeMinutes, offTimeMinutes, steamBoiler, days }]

Makine Kontrol Komutlari

Tum komutlar Promise<boolean> doner. true = basarili, false = basarisiz/timeout.

Guc Kontrolu

// Makineyi ac
await machine.setPower(true);

// Makineyi kapat (StandBy)
await machine.setPower(false);

Kahve Kazani Sicakligi

// Sicakligi 93°C yap
await machine.setCoffeeTargetTemperature(93);

// Sicakligi 0.1 derece hassasiyetle ayarla
await machine.setCoffeeTargetTemperature(94.5);

Buhar Kazani

// Buhar kazanini ac/kapat
await machine.setSteam(true);
await machine.setSteam(false);

Buhar seviyesi (sadece Linea Micra ve Linea Mini R):

import { SteamTargetLevel } from './src/index.js';

await machine.setSteamLevel(SteamTargetLevel.LEVEL_1); // 126°C
await machine.setSteamLevel(SteamTargetLevel.LEVEL_2); // 128°C
await machine.setSteamLevel(SteamTargetLevel.LEVEL_3); // 131°C

Buhar sicakligi (sadece GS3, GS3 MP, GS3 AV):

await machine.setSteamTargetTemperature(128);

Backflush (Temizlik)

// Backflush baslatmak icin makineye kör sifon takin ve calistirin:
await machine.startBackflush();

// Backflush durumunu kontrol et:
const dashboard = await machine.getDashboard();
const backflush = dashboard.config['CMBackFlush'];
// backflush.status -> 'Off' | 'Requested' | 'Cleaning'
// backflush.lastCleaningStartTime -> Date | null

Pre-Extraction (On-Demleme)

import { PreExtractionMode } from './src/index.js';

// Modu degistir
await machine.setPreExtractionMode(PreExtractionMode.PREINFUSION);
await machine.setPreExtractionMode(PreExtractionMode.PREBREWING);
await machine.setPreExtractionMode(PreExtractionMode.DISABLED);

// Pre-extraction surelerini ayarla (saniye)
await machine.setPreExtractionTimes(2.0, 3.5); // on-sure: 2s, off-sure: 3.5s

Smart Standby

import { SmartStandByType } from './src/index.js';

// Son demlemeden 30 dakika sonra standby'a gec
await machine.setSmartStandby(true, 30, SmartStandByType.LAST_BREW);

// Acildiginda 45 dakika sonra standby'a gec
await machine.setSmartStandby(true, 45, SmartStandByType.POWER_ON);

// Smart standby'i kapat
await machine.setSmartStandby(false, 30, SmartStandByType.LAST_BREW);

Zamanlama (Wake-Up Schedule)

import { WeekDay } from './src/index.js';

// Yeni bir zamanlama olustur
await machine.setWakeupSchedule({
  enabled: true,
  onTimeMinutes: 420,           // 07:00 (gun baslasindan dakika)
  offTimeMinutes: 1080,         // 18:00
  steamBoiler: true,            // Buhar kazani da acilsin
  days: [WeekDay.MONDAY, WeekDay.TUESDAY, WeekDay.WEDNESDAY,
         WeekDay.THURSDAY, WeekDay.FRIDAY],
});

// Mevcut zamanlamalari gor
const schedule = await machine.getSchedule();
for (const s of schedule.smartWakeUpSleep.schedules) {
  console.log(s.id, s.enabled, s.days, s.onTimeMinutes, s.offTimeMinutes);
}

// Zamanlamayi sil
await machine.deleteWakeupSchedule('zamanlama-id');

Brew by Weight / Tartili Demleme (sadece Linea Mini / Mini R)

import { DoseMode } from './src/index.js';

// Doz modunu degistir
await machine.setBrewByWeightDoseMode(DoseMode.DOSE_1);
await machine.setBrewByWeightDoseMode(DoseMode.DOSE_2);
await machine.setBrewByWeightDoseMode(DoseMode.CONTINUOUS);

// Doz degerlerini ayarla (gram)
await machine.setBrewByWeightDose(DoseMode.DOSE_1, 36.0);  // Dose 1 = 36g
await machine.setBrewByWeightDose(DoseMode.DOSE_2, 18.5);  // Dose 2 = 18.5g

Istatistikler

// Son 7 gunun kahve/flush trendi
const trend = await machine.getCoffeeAndFlushTrend(7, 'Europe/Istanbul');
// trend.coffees -> [{ timestamp: Date, value: 5 }, ...]

// Son kahveler
const lastCoffees = await machine.getLastCoffee(7);
// lastCoffees.lastCoffees -> [{ time: Date, extractionSeconds: 28.5, doseMode: 'Dose1', ... }]

// Toplam kahve/flush sayaci
const counter = await machine.getCoffeeAndFlushCounter();
// counter.totalCoffee -> 1234
// counter.totalFlush  -> 56

WebSocket (Gercek Zamanli Guncellemeler)

Dashboard verilerini anlik olarak dinlemek icin WebSocket baglantisi kullanilir.

// WebSocket baglan (bu promise surekli acik kalir)
machine.connectDashboardWebsocket({
  onUpdate: (config) => {
    console.log('Dashboard guncellendi:', Object.keys(config.config));

    const status = config.config['CMMachineStatus'];
    if (status) {
      console.log('Makine modu:', status.mode);
      console.log('Demleme basladi mi:', status.brewingStartTime);
    }
  },
  onConnect: () => console.log('WebSocket baglandi'),
  onDisconnect: () => console.log('WebSocket koptu'),
  autoReconnect: true,  // Kopunca otomatik tekrar baglan
});

// Baska bir yerden WebSocket'i kapat
await client.websocketDisconnect();

Firmware

// Firmware durumunu kontrol et
const fw = await machine.getFirmware();
// fw.status -> 'Updated' | 'ToUpdate' | 'InProgress' | 'Pending'

// Firmware guncelle
await machine.updateFirmware();

Enum Referansi

MachineMode

| Deger | Aciklama | |-------|----------| | 'BrewingMode' | Acik, demlemeye hazir | | 'StandBy' | Bekleme modu |

MachineState

| Deger | Aciklama | |-------|----------| | 'PoweredOn' | Acik | | 'StandBy' | Bekleme | | 'Brewing' | Demleme yapiliyor | | 'Off' | Kapali |

SteamTargetLevel (Micra/Mini R)

| Deger | Sicaklik | |-------|----------| | 'Level1' | 126°C | | 'Level2' | 128°C | | 'Level3' | 131°C |

PreExtractionMode

| Deger | Aciklama | |-------|----------| | 'PreInfusion' | On-demleme (pre-infusion) | | 'PreBrewing' | On-demleme (pre-brewing) | | 'Disabled' | Kapali |

SmartStandByType

| Deger | Aciklama | |-------|----------| | 'LastBrewing' | Son demlemeden sonra sayacı baslatir | | 'PowerOn' | Acildiginda sayaci baslatir |

DoseMode

| Deger | Aciklama | |-------|----------| | 'Continuous' | Surekli demleme | | 'Dose1' | 1. doz | | 'Dose2' | 2. doz |

BackFlushStatus

| Deger | Aciklama | |-------|----------| | 'Off' | Kapali | | 'Requested' | Istendi | | 'Cleaning' | Temizlik yapiliyor |

BoilerStatus

| Deger | Aciklama | |-------|----------| | 'StandBy' | Bekleme | | 'HeatingUp' | Isiniyor | | 'Ready' | Hazir | | 'NoWater' | Su yok | | 'Off' | Kapali |

WeekDay

'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'

ModelCode

| Deger | Makine | |-------|--------| | 'LINEAMINI' | Linea Mini | | 'LINEAMICRA' | Linea Micra | | 'LINEAMINIR' | Linea Mini R | | 'GS3' | GS3 | | 'GS3MP' | GS3 MP | | 'GS3AV' | GS3 AV |

Widget Tipleri (Dashboard Config Keys)

Dashboard'dan donen config objesi bu key'lerle erisilir:

| Key | Aciklama | Hangi Makinelerde | |-----|----------|-------------------| | CMMachineStatus | Makine durumu, mod, demleme zamani | Hepsi | | CMCoffeeBoiler | Kahve kazani sicakligi ve durumu | Hepsi | | CMSteamBoilerLevel | Buhar kazani seviyesi (Level1-3) | Micra, Mini R | | CMSteamBoilerTemperature | Buhar kazani sicakligi | GS3, Mini | | CMPreExtraction | Pre-extraction ayarlari (basit) | Hepsi | | CMPreBrewing | Pre-brewing ayarlari (detayli) | Hepsi | | CMBackFlush | Backflush durumu | Hepsi | | CMRinseFlush | Durulama ayarlari | Hepsi | | CMGroupDoses | Grup doz ayarlari | Hepsi | | CMBrewByWeightDoses | Tartili demleme dozlari | Mini, Mini R | | CMHotWaterDose | Sicak su dozu | Secili modeller | | CMNoWater | Su alarmı | Hepsi | | ThingScale | Bagli terazi bilgisi | Mini, Mini R |

Hata Yonetimi

import {
  LaMarzoccoError,
  AuthFail,
  RequestNotSuccessful,
  CloudOnlyFunctionality,
  UnsupportedModel,
} from './src/index.js';

try {
  await machine.setPower(true);
} catch (err) {
  if (err instanceof AuthFail) {
    console.error('Yanlis kullanici adi veya sifre');
  } else if (err instanceof UnsupportedModel) {
    console.error('Bu ozellik makinenizde desteklenmiyor:', err.message);
  } else if (err instanceof RequestNotSuccessful) {
    console.error('API hatasi:', err.message);
  }
}

Dosya Yapisi

src/
  index.js                  # Tum export'lar
  const.js                  # Enum'lar ve sabitler
  exceptions.js             # Hata siniflari
  clients/
    cloud-client.js         # REST + WebSocket istemcisi
  devices/
    thing.js                # Temel cihaz sinifi
    machine.js              # Kahve makinesi sinifi
  models/
    index.js                # Model export'lari
    authentication.js       # Token modelleri
    config.js               # Dashboard widget parser'lari
    general.js              # Thing, CommandResponse
    schedule.js             # Zamanlama modelleri
    statistics.js           # Istatistik modelleri
    update.js               # Firmware modelleri
  util/
    authentication.js       # ECDSA imzalama, proof algoritmasi
    websocket.js            # STOMP frame encode/decode