Module Planner

Le module Planner permet de gérer des plannings horaires pour piloter les consignes de puissance active et de réserve d'une entité (onduleur, batterie, centrale, etc.). Il s'appuie sur la configuration CMD_REGULATION pour exécuter les commandes Modbus.

Vue d'ensemble

Le module Planner fonctionne avec deux composants principaux :

planning_sync : Commande de synchronisation qui reçoit et stocke les plannings journaliers
planning_execute : Script d'exécution automatique qui applique les consignes horaires

Fonctionnalités

Définition de consignes horaires sur une journée
Gestion des rampes de montée et descente en puissance
État par défaut configurable (ON/OFF)
Support multi-réserves (primaire, secondaire)
Agrégation temporelle configurable
Intégration avec CMD_REGULATION pour l'exécution

Prérequis

L'entité doit avoir l'attribut CMD_REGULATION configuré avec les cibles de régulation :

{
  "target_name": {
    "peak_power": 1500,
    "on": {
      "register": 2000,
      "byte_order": "ABCD",
      "controller": "modbus1",
      "data_type": "int16",
      "slave_id": 1,
      "value": 0
    },
    "off": {
      "register": 2000,
      "byte_order": "ABCD",
      "controller": "modbus1",
      "data_type": "int16",
      "slave_id": 1,
      "value": 1
    },
    "power": {
      "register": 2001,
      "byte_order": "ABCD",
      "data_type": "int32",
      "length": 2
    },
    "percent": {
      "register": 2002,
      "byte_order": "ABCD",
      "data_type": "int16"
    }
  }
}

Structure du planning

Format YAML

planning_ident: "12345678-1234-1234-1234-123456789123"
creation_date: 1761830251
default_state: "ON"
aggregation_period: 3600
ramp_up: 5
ramp_down: 5
planning:
  "12:00:00":
    planning_name: "PSN"
    state: "OFF"
    active_power: 0
    primary_reserve_power: 0
    secondary_reserve_power: 0
    mode: 0
  "14:00:00":
    planning_name: "Production"
    state: "ON"
    active_power: 750
    primary_reserve_power: 50
    secondary_reserve_power: 100
    mode: 1

Paramètres du planning

Paramètre	Type	Description
`planning_ident`	string	Identifiant unique du planning
`creation_date`	int	Timestamp Unix de création
`default_state`	string	État par défaut : `ON` ou `OFF`
`aggregation_period`	int	Période d'agrégation en secondes
`ramp_up`	int	Temps de montée en puissance (minutes)
`ramp_down`	int	Temps de descente en puissance (minutes)

Paramètres des entrées de planning

Paramètre	Type	Description
`planning_name`	string	Nom/libellé de la consigne
`state`	string	État : `ON`, `OFF` ou `TARGET`
`active_power`	float	Puissance active en kW
`primary_reserve_power`	float	Réserve primaire en kW
`secondary_reserve_power`	float	Réserve secondaire en kW
`mode`	int	Mode de fonctionnement (optionnel)

Commande planning_sync

La commande planning_sync permet de recevoir et stocker un planning journalier.

Variables de commande

Variable	Type	Obligatoire	Description
`date`	string	Oui	Date d'exécution (YYYY-MM-DD)
`planning_ident`	string	Oui	Identifiant unique du planning
`planning`	JSON	Oui	Définition des consignes horaires
`creation_date`	int	Oui	Timestamp Unix de création
`default_state`	string	Oui	État par défaut
`aggregation_period`	int	Oui	Période d'agrégation (secondes)
`ramp_up`	int	Oui	Temps de montée (minutes)
`ramp_down`	int	Oui	Temps de descente (minutes)

Exemple d'appel API

POST https://api.alemca.io/v3/commands/tasks/<task_ident>/jobs
Content-Type: application/json
api-key: <your-api-key>

{
  "entity_ident": "<entity_ident>",
  "variables": {
    "date": "2026-01-15",
    "planning_ident": "planning-site-001",
    "creation_date": 1762420922,
    "default_state": "ON",
    "aggregation_period": 60,
    "ramp_up": 5,
    "ramp_down": 5,
    "planning": {
      "17:40:00": {
        "planning_name": "PSN",
        "state": "OFF",
        "active_power": 0,
        "primary_reserve_power": 0,
        "secondary_reserve_power": 0,
        "mode": 0
      },
      "17:45:00": {
        "planning_name": "Production",
        "state": "ON",
        "active_power": 750,
        "primary_reserve_power": 0,
        "secondary_reserve_power": 0,
        "mode": 0
      }
    }
  }
}

États de consigne

ON

L'équipement est actif. La commande on est envoyée à toutes les cibles configurées.

OFF

L'équipement est arrêté. La commande off est envoyée à toutes les cibles configurées.

TARGET

La puissance cible (active_power) est appliquée via le bloc power ou percent selon la configuration disponible.

Si seul le bloc percent est configuré et peak_power est défini, la conversion automatique est effectuée :

percent = (active_power / peak_power) × 100

Période d'agrégation

La période d'agrégation définit l'intervalle de communication :

Valeur	Description
`60`	Communication par minute
`900`	Communication par quart d'heure
`1800`	Communication par demi-heure
`3600`	Communication par heure

Rampes de transition

Les paramètres ramp_up et ramp_down permettent d'éviter les variations brusques de puissance :

ramp_up : Temps de montée lors du passage à une puissance supérieure
ramp_down : Temps de descente lors du passage à une puissance inférieure

Valeur 0 = changement instantané (déconseillé pour les équipements de puissance).

Chemins de fichiers

Fichier	Chemin
Planning journalier	`/etc/alemca/system/planning/planning-YYYY-MM-DD.yaml`
État d'exécution	`/etc/alemca/system/planning/state/`
Configuration	`/etc/alemca/configs/planning.yml`

Idempotence

Le module Planner assure l'idempotence des commandes :

L'état est suivi par fichier pour chaque planning_ident
Une consigne n'est exécutée qu'une seule fois par slot temporel
Les exécutions dupliquées sont ignorées

Exemple de planning journalier

Planning pour un cycle arrêt/production/réduction :

planning_ident: "site-photovoltaic-001"
creation_date: 1762420922
default_state: "ON"
aggregation_period: 3600
ramp_up: 5
ramp_down: 5
planning:
  "06:00:00":
    planning_name: "Démarrage"
    state: "ON"
    active_power: 500
    primary_reserve_power: 0
    secondary_reserve_power: 0
    mode: 0
  "12:00:00":
    planning_name: "Arrêt midi"
    state: "OFF"
    active_power: 0
    primary_reserve_power: 0
    secondary_reserve_power: 0
    mode: 0
  "14:00:00":
    planning_name: "Production maximale"
    state: "ON"
    active_power: 1500
    primary_reserve_power: 100
    secondary_reserve_power: 50
    mode: 1
  "18:00:00":
    planning_name: "Réduction"
    state: "TARGET"
    active_power: 300
    primary_reserve_power: 0
    secondary_reserve_power: 0
    mode: 0
  "20:00:00":
    planning_name: "Arrêt soir"
    state: "OFF"
    active_power: 0
    primary_reserve_power: 0
    secondary_reserve_power: 0
    mode: 0

Notes techniques

Format horaire : Les heures doivent être au format HH:MM:SS (ex: 09:30:00)
Ordre chronologique : Les consignes sont traitées dans l'ordre chronologique
Journée complète : Le planning couvre une journée de 00:00:00 à 23:59:59
Default state : Utilisé pour les périodes non couvertes par le planning
Timestamp Unix : creation_date doit être un timestamp Unix (secondes depuis 1970-01-01)

Dépannage

Problème	Cause possible	Solution
Consigne non exécutée	`CMD_REGULATION` manquant	Configurer l'attribut sur l'entité
Erreur de format	Date invalide	Utiliser le format `YYYY-MM-DD`
Planning non trouvé	Fichier absent	Vérifier l'exécution de `planning_sync`
Cible non trouvée	Nom de cible incorrect	Vérifier `CMD_REGULATION`

Voir aussi

Régulation Centrale - Configuration CMD_REGULATION
Module Modbus - Communication Modbus
API Commandes - API de commandes