Dokumentation

HTTP API

Die folgenden Funktionen liefern eine Abbildung der Modbus-Register in HTTP.
Hinweis: Modbus muss nicht aktiv sein, um das HTTP API nutzen zu können.

Benutzen Sie einen HTTP GET oder POST request an die Adresse des cFos Power Brain Controllers, z.B.
http://192.168.2.111/cnf?cmd=modbus&device=meter1&read=35154.
Die Antworten erfolgen in JSON.

  • cmd ist immer modbus
  • device = meter1 oder meter2 oder evse
  • read = Adresse des zu lesenden Registers
  • write = Adresse des zu schreibenden Registers
  • value = zu schreibender Wert
  • values = Array von zu schreibenden Werten, z.B. [1,2,3,4]

Adressen können einen Suffix haben, um den Datentyp festzulegen (Default ist 16 bit Integer):

  • d = 32 bit Integer (2 Modbus-Register)
  • q = 64 bit Integer (4 Modbus-Register)
  • s = String
cFos Power Brain Controller - Modbus-Register

Hier einige Beispiele für die Nutzung des HTTP API

Modbus

/cnf?cmd=modbus&device=meter1&read=8002
Antwort:
1

/cnf?cmd=modbus&device=meter1&read=8062d
Antwort:
-1

/cnf?cmd=modbus&device=meter1&read=8016s
Antwort:
"cFos Power Brain"

/cnf?cmd=modbus&device=meter1&read=8002&count=10
Antwort:
[1,257,256,0,256,0,26211,26165,11619,13366]

/cnf?cmd=modbus&device=meter2&read=all
Antwort:
{"8000d":-821755904,"8002":1,"8003":257,"8004":16777216,"8006":256,"8007":0,"8008s":"fcf5-c46d-310c","8016s":"cFos Power Brain","8040":41,"8041":1,"8042d":1000,"8044":1,"8045":230,"8046":230,"8047":230,"8050q":0,"8054d":0,"8056":0,"8057":0,"8058q":0,"8062d":-1,"8064d":0,"8066d":0,"8068d":0,"8070":0,"8071":0,"8120d":0}

/cnf?cmd=modbus&device=evse&write=8044&value=7
Antwort:
"ok"

/cnf?cmd=modbus&device=evse&write=8050q&value=1"
Antwort:
"ok"

/cnf?cmd=modbus&device=evse&write=8044d&value=1"
Antwort:
"bad modbus register size"

/cnf?cmd=modbus&device=evse&write=8044&values=[7,230,230,230 ]
Antwort:
"ok"

Allgemeine Requests

Abfragen des Zustands aller Charging Manager Geräte:
/cnf?cmd=get_dev_info

Setzen einer PIN bzw. RFID:
/cnf?cmd=enter_rfid&rfid=r&dev_id=d
r ist die PIN bzw. RFID (Ziffern), d ist eine optionale device id, um eine bestimmte Wallbox auszuwählen. Wird keine device id gewählt, versucht der Charging Manager die PIN bzw. RFID automatisch zuzuordnen.

Überschreiben für aktuelle Transaktion:
/cnf?cmd=override_device&dev_id=d&flags=f&mamps=ma&rfid=id
d ist die Device ID, id ist eine evtl. nötige RFID/PIN, flags, wie folgt:
'C': Laden deaktiveren (Admin pwd oder Benutzr PIN/RFID erforderlich)
'c': Deaktivierung des Laden wieder aufheben (Admin pwd oder Benutzr PIN/RFID erforderlich)
'E': Laderegeln der Wallbox deaktiveren (Admin pwd erforderlich)
'e': Deaktivierung der Laderegeln der Wallbox wieder aufheben (Admin pwd erforderlich)
'U': Laderegeln der Benutzers deaktiveren (Benutzer RFID/PIN erforderlich)
'u': Deaktivierung der Laderegeln des Benutzers wieder aufheben (Benutzer RFID/PIN erforderlich)

Die so gesetzten flags bleiben erhalten, bis das Auto aus der Wallbox ausgesteckt wird.

mamps=ma: Ladestrom mit ma mA überschreiben (limitieren).

Setzen des simulierten Energiezählers:
/cnf?cmd=soft_meter&dev_id=d&val=v
v (optional) ist die zu setzende Energy in Wh/VAh. Ist v nicht vorhanden, wird der Zähler nur gelesen. d ist die device id der Wallbox. Rückgabewert ist der alte Zählerstand vor dem Setzen.

HTTP Zähler und Wallboxen

Zähler

Sie können einen Zähler anlegen (Gerätetyp 'HTTP Input'), der nicht vom Charging Manager ausgelesen, sondern dessen aktuelle Werte von außen mittels HTTP POST oder GET vorgegben werden können:
/cnf?cmd=set_ajax_meter&dev_id=x
x ist die Device ID, wie in der Geräte Konfiguration zu sehen, z.B. M1.

Der POST body enthält ein JSON-Object, wie folgt:

{
            "model": string,
            "import_vah": number,
            "export_wh": number,
            "voltage": [v1, v2, v3],
            "current": [c1, c2, c3],
            "power_w": number
            "is_va": bool
         }

Hierbei werden Energiewerte in Wh, Spannungen in V, Ströme in mA und Leistungen in W angegeben. "model" ist der Model-String, wie in den Kacheln angezeigt.

Einige unserer User (#diebestenuserderwelt) nutzen das Tool curl, um den Zähler mit Daten zu beliefern, z.B.:
curl -i -X POST -H 'Content-Type: application/json' -d '{ "model": "TestModell", "import_wh": 12345, "export_wh": 23456, "voltage": [231, 232, 233], "current": [10001, 10002, 10003] }' --user admin:1234abcd 'http://192.168.2.111/cnf?cmd=set_ajax_meter&dev_id=M3'

Als HTTP GET schreibt sich der request so:
http://192.168.2.111/cnf?cmd=set_ajax_meter&dev_id=M3&model=TestModell&import_wh=12345&export_wh=23456&voltage=231,232,233&current=10001,10002,10003

Hier noch ein Forumsbeitrag zur Anbindung eines Smartmeters mittels cFos HTTP Input Zähler und ioBroker.

Wallbox

Sie können auch eine Wallbox anlegen (Gerätetyp 'HTTP Input'), die nicht vom Charging Manager ausgelesen bzw. gesteuert wird, sondern deren Werte von außen mittels HTTP POST oder GET vorgegeben werden können. Die Steuerwerte werden dann als Antwort zurückgeliefert:
/cnf?cmd=set_ajax_evse&dev_id=x
x ist die Device ID, wie in der Geräte Konfiguration zu sehen, z.B. E1.

Der POST body enthält ein JSON-Object, wie folgt:

{
            "state": number,
            "max_charging_current": number,
            "current": [c1, c2, c3],
            "total_energy": number,
            "model": string,
            "rfid": string
         }

"model" ist der Model-String, wie in den Kacheln angezeigt. Mit "rfid" kann man dem Ladevorgang eine RFID mitgeben, Energiewerte werden in Wh, Ströme in mA angegeben. "state" hat folgende Werte:
1 = waiting (A), 2 = EV present (B), 3 = charging (C), 4 = charging with ventilation (D), 5 = error (E)

Als HTTP GET schreibt sich der request so:
http://192.168.2.111/cnf?cmd=set_ajax_evse&dev_id=M3&model=TestModell&state=st&max_charging_current=m&current=c1,c2,c3&total_energy=t&rfid=r

Als Antwort liefert dieser request folgendes JSON-Object zurück:

{
            "device_enabled": true/false,   // Gerät ist aktiv / deaktiviert
            "charging_enabled": true/false,  // Laden erlaubt / nicht erlaubt
            "paused": true/false,   // true = Gerät ist vorübergehend pausiert
            "charging_current": number   // vorgegebener Ladestrom im mA
         }

Diese Rückgabe-Objekt muss vom Aufrufer ausgewerten und die Wallbox entsprechend eingestellt werden, z.B. der Ladestrom entsprechend geändert werden.

Web interface (English)

All requests return an answer in JSON. Values marked with r/o are read-only. Please note: We do not guarantee the stability of this API. Functionality, parameters, values, etc. may change without notice.

Retrieve info about load-balancing and all devices

/cnf?cmd=get_dev_info
Return value (sample):
         {
         "params" : {
         "title" : "cFos Power Brain",
         "desc" : "Standard-Konfiguration",
         "max_total_current" : 32000,   // total installed power in mA
         "reserve_current" : 0,   // reserve in mA (subtracted from max_total_current)       
         "overdraft_cur" : 0,       // generated overdraft in mA, can be set to 0
         "max_total_evse_current" : 0,   // max current available to all EVSEs in mA
         "cons_evse_power" : 0,    // r/o, consumed EVSE power in W
         "avail_evse_power" : 32000,   // r/o, available EVSE power in W
         "lb_enabled" : false,   // true: load balancing enabled, false: disabled (observation mode)
         "disable_policy" : 1,   // on device disable: 0 disable EVSE, 1 use min. charging current, -1 remove charging current limit (free charging)
         "cycle_time" : 3009,   // current update cycle time in msec
         "max_evses" : 3,   // maximum number of licensed EVSEs
         "shareware_mode" : false,   // false, if licensed, true if trial version
         "version" : "1.8.1095",
         "time" : 1645281534,   // current time stamp
         "vsn" : 
         {
         "vendorid" : 52997,   // cFos
         },
         "ocpp_gateway_license_cnt" : 0,  // number of licensed OCPP gateways
         "ocpp_gateway_licenses_used" : 0   // number of used OCPP gateways
         },
         "devices" : [   // array of configured devices
         {
         "dev_type" : "evse_powerbrain",   // a sample EVSE
         "device_enabled" : 1,   // 1 = device enabled, 0 = disabled
         "name" : "Wallbox",   // config item: name
         "address" : "evse",   // address: URL, IP address or COM Port + Parameters
         "id" : 1,   // Modbus ID
         "dev_id" : "E1",   // unique device ID, EVSE always begin with E
         "number" : 1,   // config item: number
         "desc" : "cFos Power Brain Wallbox 11kW",   // config item: description
         "com_err" : false,   // true, if active communication error
         "com_err_secs" : 1404660,   // time since last com error
         "com_errors" : 0,   // number of com errors
         "last_error" : "",   // text of last error
         "is_evse" : true,   // true for EVSEs, false for meters
         "used_phases" : 0,   // 0=determine, otherwise bitfield: bit0 L1, bit1 L2, bit2 L3
         "label" : "",   // config item: text displayed when plugged in
         "min_charging_cur" : 6000,   // minimum charging current in mA
         "max_charging_cur" : 11040,   // maximum charging current in mA or expression
         "prio" : 1,   // charging priority
         "charging_enabled" : true,   // r/o, true if charging allowed
         "cur_charging_power" : 0,   // r/o, current charging power in W
         "total_energy" : 7120572,   // r/o, total used charging energy in Wh
         "phases" : 0,   // currently used phases, bitfield: bit0 L1, bit1 L2, bit2 L3
         "state" : 1,   // 1 = waiting for EV, 2 = EV presend, 3 = charging, 4 = charging/vent, 5 = error, 6 = offline
         "model" : "cFos Power Brain,1.0,1.8.1095,6d-31-0c",   // r/o, model string: Manufacturer,device,device version, firmware version, serial number
         "paused" : false,   // true, if device paused due to energy shortage or phase imbalance
         "pause_time" : 300,   // current elapsed pause time in secs
         "pause_min_time" : 300,   // min. secs before end of pause
         {
         "dev_type" : "meter_powerbrain",  // a sample meter
         "device_enabled" : 1,   // 1 = device enabled, 0 = disabled
         "name" : "S0 Zähler 1",   // config item: name
         "address" : "meter1",   // address: URL, IP address or COM Port + Parameters
         "id" : 2,   // Modbus ID
         "dev_id" : "M1",   // unique device ID, meters always begin with M
         "number" : 1,   // config item: number
         "desc" : "cFos Power Brain, S0 Zähler 1",   // config item: description
         "com_err" : false,   // true, if active communication error
         "com_err_secs" : 1404660,   // time since last com error
         "com_errors" : 0,   // number of com errors
         "last_error" : "",   // text of last error
         "is_evse" : true,   // true for EVSEs, false for meters
         "used_phases" : 0,   // 0=determine, otherwise bitfield: bit0 L1, bit1 L2, bit2 L3
         "is_va" : false,   // true if display is VA, false for W
         "invert" : false,   // if true, current and power values are inverted
         "import" : 15,   // imported energy in Wh
         "export" : 0,   // exported energy in Wh
         "power_w" : 0,   // current active power in W
         "current_l1" : 0,   // current L1 in mA
         "current_l2" : 0,   // current L2 in mA
         "current_l3" : 0,   // current L3 in mA
         "voltage_l1" : 230,   // Voltage L1 in V
         "voltage_l2" : 230,   // Voltage L2 in V
         "voltage_l3" : 230,   // Voltage L31 in V
         "role" : 0,   // 0 = display, 1 = consumption, 2 = production, 3 = grid demand, 4 = vehicle consumption, 5 = storage
         "model" : "cFos Power Brain,1.0,1.8.1095,6d-31-0c"   // r/o, model string: Manufacturer,device,device version, firmware version, serial number
         }
         ]
         }
                  

Get/set Charging Manager parameters

/cnf?cmd=get_params
/cnf?cmd=set_params

HTTP GET get_params returns a JSON object, HTTP POST set_params needs a JSON object in the message body


Return value (sample):
         //         see values for get_dev_info.
         //        In Addition there is a device meta struct to allow for selection of device types:
         "dev_meta": 
         {
         "evse_powerbrain" : "cFos Power Brain",   // EVSE device type : name
         "evse_mennekes_modbus" : "Heidelberg Energy Control",
         "meter_elenker_meter" : "ModbusMeter 5A",   // meter device type : name
         "meter_kostal_powermeter" : "Kostal Powermeter",
         "meter_orno_we516" : "Orno OR-WE-516",
         }         
                  

Set device configuration

/cnf?cmd=set_params
POST payload (sample):
         {
            devices: [   // array of device objects, currently may only contain 1 device
            {   // for most of the device properties, see get_dev_info
         attach: ""   // device ID of an attached meter
         battery_save_threshold: 0   // in mA, if charging current falls below this threshold, charging will be stopped, 0 = disable
         charging_rules: [   // array of charging rules
         // charging rules are work in progress, expect frequent changes to their object layout.
         {
            "days": d,     // d is a bitfields a weekdays: bit0 Monday...bit6 Sunday
            "mode": m,     // m mode of the rule: 0=absolule current, 1=relative current, 2=current solar current, 3=relative current solar current, 4=solar current minus current value, 5=solar surplus
            "current": c,  // c current in mA
            "enabled": e,  // e = true for an active rule, false for ignored rules
            "udur": u,     // u = undercut duration in secs
            "time": t      // t in minutes after midnight (for time based rules)
            "dur":  dur    // dur in minutes (for time based rules)
            "expr": expr   // expr is evaluated to determine the rule current (for expression rules)
            "input": in    // in = string specifying the input and level (for input based rules)
            "price_level", p   // p = price level (for cost baseed rules)
            "solar": s     // solar current in mA (for solar based rules)
         }
         ]
         enable_snooze: true   // true, allow device snooze
         enable_wakeup: true   // true, allow device wakeup for charging
         fixed_rfid: ""   // use fixed RFID for OCPP
         group: 0   // device belongs to this group, 0 = main group
         ocpp_gateway_client_id: "CP42"
         phase_rotation: 0
         soft_meter: 7120572   // estimated charged energy in W (if device has no meter)
         users: ["1170223812"]   // array of user ids which are allowed to charge at this EVSE
            ]
         }
                  

Get / set user info

/cnf?cmd=get_users
/cnf?cmd=get_user
/cnf?cmd=set_user
*** ml: String not found [name='cfos_cm_sample_resp']:
:
         // get_user retrieves a single user object, set_user POSTs a single user object, get_users retrieves an array of user objects
         // set_user may be called without admin password if it contains a valid user ID, creation of new users requires admin access

         [   // array of users
         {
         "id" : "2167520770",   // unique user ID
         "name" : "wusel",   // name
         "display" : true,   // true if user may be displayed while plugged in
         "dev_ids" :    // EVSEs the user may use
         [
         "E1"
         ],
         "rfids" : 
         [   // array of RFIDs
         {
         "id" : "4711",   // RFID / PIN
         "name" : "TeSt",   // Name
         "ac_auth" : true,   // true: used to authorize
         "ac_ovch" : false,  // true: used to stop charging
         "used_phases" : 7   // used to override used phases, 0 = don't override
         }
         ],
         "charging_rules" : 
         [   // array of charging rules for this user
         ]
         }
         ]
                  

Accept license:
/cnf?cmd=accept_license&acc=1&allow_usage_stats=a
a = 1 allow reporting of usage stats to cFos eMobililty, a = 0 disallow

Change admin password:
/cnf?cmd=change_admin_pwd&old_pwd=old&new_pwd=new
old, new are the old and new admin password

Delete a device:
/cnf?cmd=del_device&dev_id=d
d is a valid device ID

Get a unique user ID (for creation of a new user):
/cnf?cmd=get_new_user_id
returns a new user ID as a JSON string

Reset a device:
/cnf?cmd=reset_device&dev_id=d
d is a valid device ID. The device will be destroyed and re-created

Start stop diagnose logging:
/cnf?cmd=set_diag_logging&enable=e
e = 1 to start, e = 0 to stop diagnose logging. Runs for 5 minutes if not stopped