Documentation

HTTP API

The following functions provide a mapping of the Modbus Registers to HTTP.
Note: Modbus does not need to be active to use the HTTP API.

Use a HTTP GET or POST request to the address of the cFos Power Brain Controller, e.g.
http://192.168.2.111/cnf?cmd=modbus&device=meter1&read=35154.
Responses are in JSON.

  • cmd is always modbus
  • device = meter1 or meter2 or evse
  • read = address of the register to read
  • write = address of the register to read
  • value = value to write
  • values = array of values to write, e.g. [1,2,3,4]

Addresses can have a suffix to specify the data type (default is 16 bit integer):

  • d = 32 bit integer (2 modbus registers)
  • q = 64 bit integer (4 modbus registers)
  • s = string
cFos Power Brain Controller - Modbus Registers

Here are some examples, how to use the HTTP API

Modbus

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

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

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

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

/cnf?cmd=modbus&device=meter2&read=all
Response:
{"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
Response:
"ok"

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

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

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

General Requests

Request the state of all Charging Manager devices:
/cnf?cmd=get_dev_info

Setting a PIN or RFID:
/cnf?cmd=enter_rfid&rfid=r&dev_id=d
r is the PIN or RFID (digits), d is an optional device id to select a specific EVSE. If no device id is selected, the Charging Manager tries to assign the PIN or RFID automatically.

Overwrite for current transaction:
/cnf?cmd=override_device&dev_id=d&flags=f&mamps=ma&rfid=id
d is the device ID, id is a possibly required RFID/PIN, flags, as follows:
'C': Disable charging (Admin pwd or User PIN/RFID required)
'c': Disable charging again (Admin pwd or User PIN/RFID required)
'E': Disable EVSE charging rules (Admin pwd required)
'e': Disable EVSE charging rules again (Admin pwd required)
'U': Deactivate user's charging rules (user RFID/PIN required)
'u': Deactivate user's charging rules again (user RFID/PIN required)

The flags set in this way remain until the car is unplugged from the EVSE.

mamps=ma: Overwrite (limit) charging current with ma mA.

Setting the simulated energy meter:
/cnf?cmd=soft_meter&dev_id=d&val=v
v (optional) is the energy to be set in Wh/VAh. If v is not present, the meter is only read. d is the device id of the EVSE. Return value is the old meter reading before setting.

HTTP meters and EVSEs

Meter

You can create a meter (device type 'HTTP Input') that is not read by the Charging Manager, but whose current values can be specified externally via HTTP POST or GET:
/cnf?cmd=set_ajax_meter&dev_id=x
x is the device ID as seen in the device configuration, e.g. M1.

The POST body contains a JSON object, as follows:

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

Here, energy values are given in Wh, voltages in V, currents in mA and powers in W. "model" is the model string as shown in the tiles.

Some of our users (#diebestenuserderwelt) use the tool curl to supply the meter with data, e.g.:
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'

As HTTP GET the request is written like this:
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

Here is another forum post about connecting a smart meter using cFos HTTP input meters and ioBroker.

EVSE

You can also create a wallbox (device type 'HTTP Input') that is not read or controlled by the Charging Manager, but whose values can be specified externally using HTTP POST or GET. The control values are then returned as a response:
/cnf?cmd=set_ajax_evse&dev_id=x
x is the device ID as seen in the device configuration, e.g. E1.

The POST body contains a JSON object, as follows:

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

"model" is the model string as shown in the tiles. With "rfid" you can add a RFID to the charging process, energy values are given in Wh, currents in mA. "state" has the following values:
1 = waiting (A), 2 = EV present (B), 3 = charging (C), 4 = charging with ventilation (D), 5 = error (E)

As HTTP GET the request is written like this:
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

In response, this request returns the following JSON object:

{
             "device_enabled": true/false, // device is enabled/disabled
             "charging_enabled": true/false, // charging allowed / not allowed
             "paused": true/false, // true = device is temporarily paused
             "charging_current": number // specified charging current in mA
         }

This return object must be evaluated by the caller and the EVSE must be set accordingly, e.g. the charging current must be changed accordingly.

Web interface

All requests return a response in JSON. The values labelled r/o are read-only. Please note: We do not guarantee the stability of this API. Functionality, parameters, values etc. are subject to change without notice.

Retrieve information about load balancing and all devices

/cnf?cmd=get_dev_info
Return values (example):
         {
         "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
         }
         ]
         }
                  

Set/read Charging Manager parameters

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

HTTP GET get_params returns a JSON object,
HTTP POST set_params requires a JSON object in the message text

Return values (example):
         //         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 settings

/cnf?cmd=set_params
POST user data (example):
         {
            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
            ]
         }
                  

Benutzerinformationen setzen/auslesen

/cnf?cmd=get_users
/cnf?cmd=get_user
/cnf?cmd=set_user

get_user retrieves a single user object,
set_user POSTs a single user object,
get_users retrieves an array of user objects
set_user can be called without an admin password if it contains a valid user ID. Creating new users requires admin access

Return values (example):
         [   // 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 licence

/cnf?cmd=accept_license&acc=1&allow_usage_stats=a
a = 1 allows the reporting of usage statistics to cFos eMobililty, a = 0 prohibits it

Change admin password

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

Delete a device

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

Retrieve a unique user ID (to create a new user)

/cnf?cmd=get_new_user_id
returns a new user ID as a JSON string

Resetting a device

/cnf?cmd=reset_device&dev_id=d
d is a valid device ID. The device is deleted and recreated

Start/stop diagnostic logging

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