NRGkick Wallbox

This function block controls an NRGkick charging cable. In automatic mode the charging current is controlled so that only the PV surplus is charged.

The block can talk to two device generations. The API variant parameter selects which one is used:

NRGkick local API for the current devices of the second generation. The manufacturer calls them Gen2, the spelling V2 is common as well. The charging cable is addressed directly over the network, no gateway is required. The interface has to be switched on in the NRGkick app under Advanced > Local API (item JSON API). It is available from SmartModule version 4.0.0.0 onwards. If the app additionally requires authentication, enter user name and password.
NRGkick gateway for existing installations with the older NRGkick Connect gateway, that is the devices of the first generation, Gen1 or V1. The charging cable is connected to the gateway via Bluetooth, therefore the Bluetooth address of the charging cable is required as well.

Which generation is present can be determined with a browser. Call the IP address of the device with the addition /info, for example http://192.168.1.125/info:

A text appears in which model_type reads "NRGkick Gen2": a device of the second generation, the local API applies. The same text contains the SmartModule version under versions at sw_sm and the data of the attached attachment under connector at phase_count and max_current.
The note appears that the API first has to be enabled in the NRGkick app: also a device of the second generation, only the interface is still switched off.
No answer at all: either the device cannot be reached, or the address belongs to a gateway of the first generation. With the gateway the call http://IP-address/api/devices returns the list of the charging cables connected by Bluetooth, which also contains the address for the parameter BT MAC of the charging cable.

If the page is not displayed, note that the call has to be made from a device in the same network as the controller. More about this in the troubleshooting section.

The device should have a fixed IP address in the local network. Communication is strictly local, an internet connection is not required.

Important: If the connection to the device is lost, the charging cable keeps the last charging current that was sent and continues to charge. Charging is therefore not stopped automatically. The communication error output reports the failure.

Inputs
BA	Operating mode*	Operating mode: 0=Automatic: surplus control 1=Manual: manual charging with the current value from input manual charging current. 2=Off: charging blocked. 3=Offline: in this mode no commands are sent to the charging cable, the status is still read. This allows parallel operation with the NRGkick app. In this operating mode a charging cable that cannot be reached is not treated as a fault. An NRGkick is a charging cable that is not permanently plugged in, and then it does not answer over the network either. The output communication error therefore stays at 0 and no messages appear in the log. Polling continues nevertheless, so as soon as the charging cable is connected to the mains again the values are up to date. If the parameter Debug is switched on, the messages are written in this operating mode as well.
LM	Manual charging current A	Charging current for manual mode in ampere. If the input is not connected, the minimum charging current parameter is used.
PU	Current surplus*	PV surplus in W. The input must not be limited to 0, positive and negative values have to arrive at the input so that the control can react correctly. The surplus type parameter defines whether a positive or a negative value means surplus. The value has to be the balance at the grid connection point, so it must include the consumption of the wallbox. Otherwise the surplus does not drop while charging and the control ramps up to the maximum charging current.
LE	Session kWh setpoint	Maximum charging energy of the current session in kWh. When this value is reached, the operating mode is set to off and the input is reset to 0. At 0 the function is disabled.
FG	Enable	Additional enable for the surplus control. If the input is not connected, the control is always enabled.
Outputs
ER	Communication error	Output is 1 if the device cannot be reached over the network or if the local API has not been enabled in the NRGkick app. In the second case the reason is written to the log in plain text. In the operating mode offline the output stays at 0 even if the charging cable cannot be reached. See input operating mode.
LA	Current charging energy	Energy charged during the running session in kWh.
LG	Total charging energy	Total energy charged with this charging cable in kWh.
LL	Current charging power	Current charging power in kW. This value also drives the control: only from 0.5 kW measured charging power onwards is the current raised above the minimum. As long as the vehicle is not charging yet, the setpoint stays at the minimum.
LS	Charging status	Output is 1 while charging is in progress.
UA	Surplus charging active	Output is 1 if the surplus control is active in automatic mode.
SS	Charging current setpoint A	Setpoint that is sent to the charging cable.
SI	Charging current setpoint status A	Feedback of the charging current set in the device. The feedback can differ from the setpoint, for example if it is changed in parallel through the NRGkick app. The block detects this and writes its setpoint again.
SC	Status code	State of the device: 0 = unknown 1 = ready, no vehicle connected 2 = vehicle connected, not charging 3 = vehicle charging 6 = error 7 = vehicle is being woken up With the gateway connection the output only reports 1 or 3, because the gateway does not provide the other states.
FC	Error code	Error code of the device, 0 = no error. The meaning of the other codes is listed in the table Error codes of the device further down.
LI	Actual charging current A	Charging current that actually flows, in ampere. It can be lower than the setpoint because many vehicles draw less than specified.
Parameters
	API variant	Type of connection: NRGkick gateway for existing installations with the older gateway, that is devices of the first generation (Gen1, V1). NRGkick local API for the current devices of the second generation (Gen2, V2). A newly inserted block is preset to the local API. Which generation is present is shown by calling the IP address with the addition /info in a browser, see the description at the beginning of this page.
	IP address	IP address of the device in the local network, or the address of the gateway when connected through one. Port 80 is used. If the port differs from that, it can be appended with a colon for the local API, for example 192.168.1.30:8080. This is not possible with the connection through the gateway, there port 80 is always used. An IP address belongs here and not a device name. The device should always get the same address, so set up a fixed assignment in the router.
	BT MAC charging cable	Bluetooth address of the charging cable. The parameter is only required for the connection through the gateway and is therefore only visible when the API variant is set to NRGkick gateway. The gateway itself is not the charging cable, it only mediates: it is connected to the network and addresses the charging cable through Bluetooth. Several charging cables can be registered on one gateway, so its IP address alone is not sufficient. Only the Bluetooth address determines which charging cable is meant. If a wrong address is entered here, the gateway does answer but does not deliver any measured values, and the output communication error is set. The address consists of six two-digit hexadecimal numbers separated by colons, for example 00:1E:C0:59:30:A0. It can be found with a browser: call the IP address of the gateway with the addition /api/devices, for example http://192.168.1.200/api/devices. The gateway answers with the list of the charging cables registered on it together with their Bluetooth addresses. If only one charging cable is registered, only one address is listed. The devices of the second generation have neither a gateway nor a Bluetooth connection, the parameter does not apply there.
	User local API	User name if authentication has been switched on for the local API in the NRGkick app. If the field stays empty, access is made without authentication. The parameter is only visible when the API variant is set to NRGkick local API, the gateway has no user name.
	Password	Password of the device. With the local API it belongs to the user name, with the gateway it is the device password.
	Minimum charging current	Minimum charging current in ampere. Less than 6 A is not possible, below that no vehicle charges. If less surplus is available, charging is switched off instead of lowering the current further. How much power this current means depends on the number of phases of the connection. At 230 V, 6 A result in about 1.4 kW single-phase, about 2.8 kW two-phase and about 4.1 kW three-phase. At least this much has to be available before charging is possible at all. The function block does not take the number of phases into account by itself, it has to be considered for the parameter start at surplus. The number of phases of the attached attachment is shown in the documentation of the local API on the device, under connector at phase_count.
	Maximum charging current	Maximum charging current in ampere, up to 32 A depending on charging cable and connection. If the device reports a lower value, that value applies.
	Gain P	Speed of the control, with a higher value the output reacts faster to a change at the input.
	Surplus type	Setting whether a positive or a negative value at the current surplus input means surplus.
	Start at surplus	Threshold in W. This surplus has to be exceeded before the charging control starts. At least the power that results from the minimum charging current is a sensible value, see parameter minimum charging current. A smaller value does let the control start, but the vehicle then draws the missing power from the grid.
	Control on time	Time in seconds the surplus has to stay above the threshold before the control starts.
	Control off time	Time in seconds without surplus until the control is stopped.
	Minimum surplus	Minimum surplus in W that is kept as a reserve during control, for example for loads that are switched on for a short time.
	Charging current dead band	Only from this deviation in ampere onwards is a new setpoint sent to the device. A small value controls more finely, a larger one reduces the network traffic.
	Repeat setpoint	Time in seconds after which the setpoint is sent again even without a change.
	Polling interval	Time in seconds between two readings of the measured values. 2 to 60 seconds can be set. With a weak WLAN a larger value helps.
	Debug	With On the sent and received data are written to the log.

Troubleshooting

The first look goes to the outputs communication error, status code and error code. This already tells whether the connection to the device cannot be established, whether no vehicle is plugged in at all, or whether the charging cable itself reports a fault.

For everything else set the parameter Debug to On. The requests that are sent (OUT) and the answers of the device (IN) are then written to the program log. Switch Debug off again after troubleshooting, otherwise entries are written on every polling interval.

A simple test independent of the function block: open the IP address of the charging cable in a browser, from a device that is in the same network as the controller. If the local API is enabled, a documentation page with the live values of the device appears. If no page comes up, the problem is in the network or in the device and not in the function block. Why a test from a mobile phone can be misleading is described in the section The controller cannot reach the charging cable.

Messages in the program log

FB_NRGKICK VALUES REJECTED: API must be enabled within the NRGkick App
The device can be reached, but the local API is not enabled. Switch on the item JSON API in the NRGkick app under Advanced > Local API. This requires SmartModule version 4.0.0.0 or newer. The same message also appears with INFO, CONTROL or CONTROL SET, depending on which request was rejected.
FB_NRGKICK CONTROL SET REJECTED: ...
The device has rejected a command, the reason follows in plain text. The most common cause is a charging current above what the device or the attachment can do, or a lock set in the device. The function block retries the command afterwards.
FB_NRGKICK ERROR GET ..., STATUS: 401
The device requires authentication, in the NRGkick app authentication is switched on for the local API. Enter user local API and password, both have to match the app exactly. If the user field is left empty, the function block accesses the device without authentication.
FB_NRGKICK ERROR GET ..., STATUS: 404
The device does not know the requested path. Either the SmartModule version is too old, in which case the charging cable has to be connected to power and to the internet to carry out the update. Or the API variant is set to local API while the entered address belongs to a gateway of the first generation.
FB_NRGKICK ERROR GET ..., STATUS: NO RESPONSE
No answer at all was received. The function block waits 2 seconds for the connection and 3 seconds for the answer. Possible causes: wrong IP address, device without power, WLAN too weak, or a network in which the controller cannot reach the charging cable at all. There is a separate section for this, The controller cannot reach the charging cable.
FB_NRGKICK ERROR: ...
Error of the HTTP interface, usually a name that cannot be resolved. Enter the IP address instead of a device name.
FB_NRGKICK ERROR JSON PARSE VALUES (also MEASUREMENTS or SETTINGS)
The answer of the device was incomplete or not valid JSON. This happens with a weak WLAN connection when the answer is cut off. A larger polling interval and better reception at the installation location solve this.
FB_NRGKICK ERROR CONNECT: ... and FB_NRGKICK TIMEOUT READ: ...
Only with the connection via the gateway. The gateway cannot be reached or does not answer. Check the IP address and the power supply of the gateway. If the gateway answers but does not deliver any measured values, the BT MAC of the charging cable is usually wrong or the charging cable is out of Bluetooth range.
FB_NRGKICK ERROR SOCKET, FB_NRGKICK ERROR SEND and FB_NRGKICK ERROR NO HOST ADDR
Also with the gateway only. NO HOST ADDR means that the entered address cannot be resolved, an IP address belongs here.
NRGKICK THREAD START FAILED
The controller could not start the polling process. This points to an overloaded controller, for example a very large number of function blocks with their own network polling. Restart the controller.
FB_NRGKICK API ACCEPTED AGAIN
Not a fault. The message confirms that the device answers again after a rejection.

The controller cannot reach the charging cable

The function block always establishes the connection from the controller to the charging cable. The charging cable therefore has to be directly reachable from the network of the controller. This is the most frequent source of errors, because the charging cable is connected by WLAN while the controller usually sits on the wired network. If a router separates the two, no connection is established even though both devices work perfectly on their own.

Testing it correctly: a test with a mobile phone says nothing in this case, because the phone is in the WLAN and therefore on the side of the charging cable. The test has to be made from a device that is in the same network as the controller, ideally from the controller itself. For this the function block network monitoring can be added to the project with the IP address of the charging cable. If it reports the device as not reachable, the fault is in the network and not in the NRGkick function block.

Controller and charging cable in different network ranges. With the usual subnet mask 255.255.255.0 the first three numbers of the IP address have to match. 192.168.1.50 for the controller and 192.168.2.30 for the charging cable are two different networks with a router in between. Remedy: bring both devices into the same network range. If the separation is intended, a route and a rule have to be set up in the router.
Second router, repeater or powerline adapter with its own network. If the WLAN of the charging cable is provided by a second router, that router usually opens its own network with its own address translation. Everything works from that network towards the outside, but not from the controller inwards. Remedy: operate the second device as an access point instead of a router, so that it only extends the existing network.
Charging cable in the guest WLAN. A guest access deliberately separates its participants from the rest of the network and only allows the way to the internet. The charging cable belongs in the normal WLAN.
Client isolation in the access point. Some access points prevent traffic between the WLAN participants. Depending on the manufacturer the setting is called client isolation, AP isolation or separate participants from each other, and it has to be switched off.
Separated networks with a firewall or VLAN. If building services and the rest of the network are separated on purpose, a rule is required that allows the controller to access the IP address of the charging cable through TCP port 80. No rule is needed in the opposite direction, the charging cable does not establish a connection to the controller by itself.
Different port. Port 80 is the standard. If a different port is used on the device, it has to be appended with a colon to the parameter IP address when the local API is used. This is not possible with the gateway, there port 80 is always used.
Device name instead of IP address. A name first has to be resolved by the controller, which often does not work in a building network. Always enter the IP address.
Changing IP address. If the charging cable gets its address through DHCP, the address can change after a restart of the router. Set up a fixed assignment for the charging cable in the router.
Weak WLAN reception at the parking space. Garages, metal doors and cellar entrances attenuate the signal considerably. Signs of this are sporadic communication errors and ERROR JSON PARSE messages, because answers are cut off. Remedy: place the access point closer or increase the polling interval.
Charging cable without mains voltage. Not a network fault, but easy to confuse with one: the charging cable can only be reached while it is plugged into the mains. If it is connected to the vehicle only, it does not answer.

Common symptoms

Communication error comes up late. The output is only set after four failed requests in a row, so that a single disturbance does not report an error. With a polling interval of 4 seconds this takes about 16 seconds.
Communication error is 1 although the device can be reached in the network. This is the case when the local API is not enabled or the authentication does not match. The reason is written in plain text to the log.
Charging does not start although surplus is available. Check in this order: operating mode is set to automatic, input enable is 1 or not connected, the surplus is above start at surplus and has been so for the duration of control on time, status code is 2 or 3 (with 1 no vehicle is plugged in). If session kWh setpoint has been reached, the function block has set the operating mode to off by itself.
Wrong API variant set. If the variant is set to local API while the address belongs to a gateway of the first generation, the log reports STATUS: 404. In the opposite case, variant gateway on a device of the second generation, no measured values arrive and the communication error stays active. Which generation is present is shown by calling the IP address with the addition /info in a browser, see the description at the beginning of this page.
The control starts, but power is drawn from the grid. The parameter start at surplus is below the power that results from the minimum charging current. On a three-phase connection that is already about 4.1 kW, on a single-phase one only about 1.4 kW. Raise the threshold to at least this power.
The charging current stays at the minimum. Control above the minimum charging current only starts once at least 0.5 kW of charging power is measured. If the vehicle does not draw any power, for example because of its own schedule in the vehicle or a charging release in the NRGkick app, the setpoint stays at the minimum.
The control runs up to the maximum charging current. In that case the input actual surplus is not the balance at the grid connection point but, for example, only the PV generation, or it is limited to 0. A wrongly set parameter type of surplus leads to the same behaviour.
Charging current setpoint status permanently differs from the setpoint. Either it is being changed in parallel through the NRGkick app, in which case the function block writes its value again, or the setpoint is above what the attached attachment can do. The function block limits the value to what the device reports by itself.
Minimum charging current below 6 A has no effect. The function block sets it to 6 A internally, below that no vehicle charges. Charging is switched off through the charging pause and not through a setpoint of 0 A.
Settings made in the NRGkick app are overwritten constantly. This is the intended function, the function block writes its setpoint again. If the app is to be used in parallel, the operating mode offline has to be used. In this operating mode the function block does not send anything and only reads the values.
After every restart of the charging cable it takes a while until the control works again. The function block writes the setpoint again after every loss of connection and, beyond that, cyclically according to the parameter repeat setpoint.
The connection is lost after some time. Usually the device has received a different IP address through DHCP. Set up a fixed assignment in the router.

Error codes of the device (output error code)

0	No error.
1	General fault. Disconnect the charging cable from the vehicle and from the supply line and plug it in again.
2	32 A attachment on a 16 A unit. Use a matching attachment.
3	Voltage drop detected. Check the supply line, the plug connection and the fuse protection, frequently the connection is dimensioned too weak.
4	Unplugging during charging detected. Charging is stopped for safety reasons. Check the plug connection, a loose contact triggers this as well.
5	Type 2 attachment not authorized.
16	Residual current detected. The residual current protection of the charging cable has tripped because the vehicle caused a residual current that was too high. If this happens repeatedly, the vehicle has to be checked.
32	Voltage error in the CP signal (control line to the vehicle).
33	Impermissible CP signal.
34	Diode fault in the vehicle. The vehicle does not comply with the standard or is defective.
48	Self test of the protective earth conductor failed. Have the electrical installation and the connection of the protective earth conductor checked by a qualified electrician.
49	Self test of the residual current protection failed.
50	Self test of the relay failed.
51	Self test of protective earth conductor and residual current protection failed.
52	Self test of protective earth conductor and relay failed.
53	Self test of residual current protection and relay failed.
54	Self test of protective earth conductor, residual current protection and relay failed.
64	Error of the supply voltage.
65	Phase shift error.
66	Overvoltage detected.
67	Undervoltage detected. At a voltage that is too low the charging cable reduces the charging current by itself in order to support the grid. If the error persists, the supply line is too weak or loaded too heavily.
68	Overvoltage without protective earth conductor detected.
69	Undervoltage without protective earth conductor detected.
70	Underfrequency detected.
71	Overfrequency detected.
72	Unknown frequency type.
73	Unknown grid type. Occurs with grid forms that the charging cable does not know, for example an IT grid or an inverter in island operation.
80	General overtemperature. Let the charging cable and the attachment cool down, make sure they are laid out freely and reduce the charging current.
81	Overtemperature in the housing.
82	Overtemperature in the attachment.
83	Overtemperature in the domestic plug. If this occurs repeatedly, the socket has to be checked, it is not suitable for the permanent charging current.

The codes apply to the connection through the local API. With the older gateway the value comes from the charging cable itself, the assignment can differ there.

Temperature and protective earth conductor errors as well as a tripped residual current protection are faults of the installation, of the socket or of the vehicle. They cannot be solved through the function block.

Notes from the manufacturer

Keep to the connection sequence: first the attachment onto the charging unit, then the power supply, last the vehicle. All plug connections have to be clean and fully plugged in.
Charging limits and schedules that are set in the NRGkick app or in the vehicle take precedence. They are the most frequent cause for a charging process that does not start at all, ends prematurely or for a charging current that cannot be changed. If such settings are used in the app, they also apply when the function block writes a higher setpoint.
For a firmware update connect the charging cable to a power source and to the internet, not plugged into the vehicle, and leave it connected for a few minutes. The local API is only available from SmartModule version 4.0.0.0 onwards.
For the charging history in the portal to be complete, the charging cable needs a WLAN connection. This is not necessary for the function block itself, it works purely locally.

Help from the manufacturer

NRGkick support
Entry page with FAQ, tutorials and downloads. It also lists the contact details of the manufacturer support: support@nrgkick.com and +43 664 401 13 50.
NRGkick FAQ
Answers to the most common faults of the device itself: charging does not start, charging stops prematurely, the charging current cannot be changed, the app does not connect, updating the firmware.
NRGkick tutorials
Video instructions, among others for the local API, for the configuration mode and for setting the charging current and charging limits. The last two are helpful when a limit set in the app restricts the control of the function block.
NRGkick downloads
Operating instructions with the chapter on faults and the meaning of the indication on the device, as well as data sheets and the app manual.
NRGkick API
Description of the local interface and how to enable it. The complete documentation with the live values can be reached directly on the device through its IP address in a browser once it has been enabled.

See also general parameters of all function blocks.

NRGkick Wallbox

Inputs

Outputs

Parameters

Troubleshooting