Keba KeContact P20 User manual

KeContact P20
Charging station
UDP Programmers Guide V 3.00
Original manual

© KEBA 2013-2023
Specifications are subject to change due to further technical developments. Details presented may be subject to correction.
All rights reserved.
Document: Revision 3.00 / Article no.: 92651
KEBA Energy Automation GmbH: Reindlstraße 51, 4040 Linz, Austria
[phone], [phone], [e-mail]
For information about KEBA and our subsidiaries please look at www.keba.com.
Comments to this manual
In this manual you will find warnings against possible dangerous situations. The used symbols apply
to the following meanings:
Notice
Notes on use of equipment and useful practical tips are identified by “Notice". Notices do not con-
tain any information that draws attention to potentially dangerous or harmful functions.
Concerning this manual
This manual is intended for use by customers and personnel with the relevant technical knowledge in
the applicable area and appropriate to the operations they are required to perform.
Target group:
•Customers/personnel with some programming knowledge
List of changes
Version: V3.00
Date: 09.01.2023
Page
Description
-
Removed all content related to P30 because there is a separate document available
-
Removed all content related to third party companies
-
Introduced new company name “KEBA Energy Automation GmbH”

Contents
3 / 12
Contents
1Introduction .................................................................................................................................... 4
1.1 Requirements........................................................................................................................ 4
2UDP commands.............................................................................................................................. 5
2.1 General information............................................................................................................... 5
2.2 Supported UDP commands .................................................................................................. 5
2.3 UDP Broadcast Messages.................................................................................................... 6
2.4 UDP command “i”.................................................................................................................. 7
2.5 UDP command “failsafe” ....................................................................................................... 7
2.6 UDP command „report“ ......................................................................................................... 8
2.7 UDP command “ena” .......................................................................................................... 10
2.8 UDP command “curr” .......................................................................................................... 10
2.9 UDP command “output” ...................................................................................................... 11
2.10 UDP command “unlock” ...................................................................................................... 11

Introduction
4 / 12
1 Introduction
The Programmers Guide provides the necessary information how to send UDP commands to your charging
station. It gives you the possibility to get status information from the charging station or control it with an UDP
Client (PC software or Smartphone App).
The User Datagram Protocol (UDP) is a simple network protocol that belongs to the transport layer of the
Internet protocol family.
With suitable Home automation controllers it is also possible to realize e.g. a reduction of your energy con-
sumption in conjunction with a photovoltaic system and your charging station.
Schematic overview (example)
1.1 Requirements
The following requirements have to be met to use the UDP functionality:
•KeContact P20 Charging station with network connection (LSA+ socket)
- Product code: KC-P20-xxxxxx2x-xxx or KC-P20-xxxxxx3x-xxx
- Firmware version: 2.5 or higher.
•Enabled UDP function with DIP-switch DWS1.3 = ON (for details about the DIP-switches please re-
fer to the “Installation manual”).
•Router or Smart-Home Server with integrated web server.
•A PC or smartphone for sending the UDP commands.
This also requires a suitable UDP Client software or UDP App.

UDP commands
5 / 12
2 UDP commands
2.1 General information
When using UDP commands it is strongly recommended to protect your Smart-Home-Network on port 7090
against unauthorized control or external attacks.
The charging station reacts on broadcasts and directly addressed commands. In a group of several charging
stations, direct addressing should be used because otherwise all charging stations would react.
The commands are sent to the charging station as simple text commands (without end characters such as
<CR> or <LF>).
The answers come as data packages with up to 512 bytes and are formatted in JSON standard; each data
line within the structure is terminated with <LF> (0x0A).
Notes:
For the JSON format, open-source-parsers are available.
UDP does not support any error correction function. Please verify the effect of the sent commands yourself.
Port information:
Send port = UDP 7090
Receive port = UDP 7090
2.2 Supported UDP commands
UDP command
Broadcast Messages
Command “i”
Command “failsafe”
Command “report”
Command “ena”
Command “curr”
Command “output”
Command “unlock”

UDP commands
6 / 12
2.3 UDP Broadcast Messages
The broadcast messages are intended to avoid the permanent polling of the following described reports.
If there is a change of the status, the authorization, the enable input X1, the maximum possible current pre-
sets (temperature reduction), or an increase of the energy value a message is generated for the change.
For a detailed evaluation of the status, the corresponding report can be queried.
UDP broadcast:
Messages:
{"State": 2}
{"Plug": 1}
{"Input": 0}
{"Enable sys": 1}
{"Max curr": 32000}
{"E pres": 999999}
Description:
"State" = Current state of the charging station
0 : starting
1 : not ready for charging; e.g. unplugged, X1 or "ena" not enabled,
RFID not enabled,.....
2 : ready for charging; waiting for EV charging request (S2)
3 : charging
4 : error
5 : authorization rejected
"Plug" = Current condition of the loading connection
0
unplugged
1
plugged on charging station
3
plugged on charging station
plug locked
5
plugged on charging station
plugged on EV
7
plugged on charging station
plug locked
plugged on EV
"Input" = State of the potential free Enable input X1.
When using the input, please pay attention to the information
in the installation manual.
"Enable sys" = Enable state for charging (contains Enable input, RFID, UDP,..).
"Max curr" = Current preset value via Control pilot in milliampere.
"E pres" = Power consumption of the current loading session in 0,1Wh;
Reset with new loading session (state = 2).
"E pres" is used as a pulse output with a valence 10Wh per message
or 100 messages / kWh -> full load 22kW
= one message every 1.6 sec

UDP commands
7 / 12
2.4 UDP command “i”
UDP command:
i
Reply:
"Firmware":"KEBA P20 v 2.5a3 (160613-061001):29309:143.0"
Description:
Returns the product family and the firmware version of the charging station.
Serves to a possible inventory of the network by means of a broadcast command
with a subsequent report for detailed queries.
2.5 UDP command “failsafe”
UDP command:
failsafe [Timeout] [curr] [save]
Reply:
"TCH-OK :done"
Description:
[Timeout] 10...600 = Within this time, a command "ena" or "curr" must be
received, in order not to activate the failsafe mode.
0 = Disables the failsafe mode.
[curr] 0 = Disables the charging process when triggering the failsafe
function, similar to command "ena 0".
6000...63000 = Reduces the maximum allowed charging current
to this value (in milliampere), when triggering the failsafe function.
[save] 0 = Activates the failsafe function only temporary until the next
startup of the device.
1 = Saves the settings into the EEPROM in order to activate the
failsafe function automatically, after restarting the device.
By default, this feature is disabled and must be enabled once or after each restart.
This function is used to limit a network charging station with a lost communication
(network error, server failure, ...) to a defined state. This can be necessary in con-
junction with a peak load limitation, in order not to overload the main fuses.
An activated failsafe function is indicated by the charging station. In this case the
LED segments do not longer illuminate the full width, but only indicates the current
state with the middle two LED segments.
A triggered failsafe function can be also recognized over UDP: in the report 2 the
"Enable sys" value goes to 0, and the charge current setting "Max curr" goes to
the default value of "Curr FS".
After the failsafe function has been activated due to a timeout, you must set the val-
ues of current and the load enable again using the associated commands "curr" and
"ena".

UDP commands
8 / 12
2.6 UDP command „report“
UDP command:
report 1
Reply:
{
"ID": "1",
"Product": "KC-P20-ES240010-000 ",
"Serial": "15017355",
"Firmware":"KEBA P20 v 2.01m11 (140610-073512)"
}
Description:
"ID" = ID of the retrieved report.
"Product-ID" = Model name (variant)
"Serial” = Serial number
"Firmware" = Firmware version
"COM-module” = Communication module is installed
"Sec" = Current system clock since restart of the charging station.
UDP command:
report 2
Reply:
{
"ID": "2",
"State": 2,
"Error1": 99,
"Error2": 99,
"Plug": 1,
"Enable sys": 1,
"Enable user": 1,
"Max curr": 32000,
"Max curr %": 1000,
"Curr HW": 32000,
"Curr user": 63000,
"Curr FS": 63000,
"Tmo FS": 0,
"Output": 0,
"Input": 0,
"Serial": "15017355",
"Sec": 4294967296,
}
Description:
"ID" = ID of the retrieved report.
"State" = Current state of the charging station
0 : starting
1 : not ready for charging; e.g. unplugged, X1 or "ena" not enabled,
RFID not enabled,.....
2 : ready for charging; waiting for EV charging request (S2)
3 : charging
4 : error
5 : authorization rejected
"Error 1" = Detail code for state 4; exceptions see FAQ on www.kecontact.com
"Error 2" = Detail code for state 4 exception #6 see FAQ on www.kecontact.com
"Plug" = Current condition of the loading connection
0
unplugged
1
plugged on charging station
3
plugged on charging station
plug locked
5
plugged on charging station
plugged on EV
7
plugged on charging station
plug locked
plugged on EV
"Enable sys" = Enable state for charging (contains Enable input, RFID, UDP,..).

UDP commands
9 / 12
"Enable user" = Enable condition via UDP.
"Max curr" = Current preset value via Control pilot in milliampere.
"Max curr %" = Current preset value via Control pilot in 0,1% of the PWM value
"Curr HW" = Highest possible charging current of the charging connection.
Contains device maximum, DIP-switch setting, cable coding and
temperature reduction.
"Curr user" = Current preset value of the user via UDP; Default = 63000mA.
"Curr FS" = Current preset value for the Failsafe function.
"Tmo FS" = Communication timeout before triggering the Failsafe function.
"Curr timer" = Shows the current preset value of currtime.
"Tmo CT" = Shows the remaining time until the current value is accepted.
"Setenergy” = Shows the set energy limit.
"Output" = State of the output X2.
"Input" = State of the potential free Enable input X1.
When using the input, please pay attention to the information
in the installation manual.
"Serial" = Serial number
"Sec" = Current system clock since restart of the charging station.
UDP command:
report 3
Reply:
{
"ID": "3",
"U1": 230,
"U2": 230,
"U3": 230,
"I1": 99999,
"I2": 99999,
"I3": 99999,
"P": 99999999,
"PF": 1000,
"E pres": 999999,
"E total": 9999999999,
"Serial": "15017355",
"Sec": 4294967296,
}
Description:
"ID" = ID of the retrieved report.
"U1"|"U2"|"U3"| = Current voltage in V.
"I1"|"I2"|"I3"| = Current current value of the 3 phases in mA.
"P" = Current power in mW (Real Power).
"PF" = Power factor in 0,1% (cosphi)
"E pres" = Power consumption of the current loading session in 0,1Wh;
Reset with new loading session (state = 2).
"total" = Total power consumption (persistent) without current loading
session 0,1Wh; Is summed up after each completed charging
session (state = 0).
"Serial" = Serial number

UDP commands
10 / 12
2.7 UDP command “ena”
UDP command:
ena [n]
Reply:
"TCH-OK :done"
Description:
[n] = Is the enable state (binary).
0 = Disabled; is indicated with a blue flashing LED.
The same as used with the external enable input.
1 = Enabled
The answer TCH-OK confirms only the receiving of the command and not the cor-
rectness of the value.
A value unequal to 0 or 1 is also confirmed and is leading to deactivation.
The correct reception can be verified using the proper report or by getting the corre-
sponding broadcast message.
ATTENTION:
Some electric vehicles (EVs) do not yet meet the standard requirements and an "ena
0" can lead to an error in the charging station.
2.8 UDP command “curr”
UDP command:
curr [n]
Reply:
"TCH-OK :done"
Description:
[n] = Is the maximum allowed loading current in milliampere.
The answer TCH-OK confirms only the receiving of the command and not the cor-
rectness of the value.
Allowed are values between 6000mA and 63000mA. Invalid values are discarded
and the default is set to 6000mA. The value is also depending on the DIP-switch
settings and the used cable of the charging station.
The correct reception can be verified using the proper report or by getting the corre-
sponding broadcast message.

UDP commands
11 / 12
2.9 UDP command “output”
UDP command:
output [n]
Reply:
"TCH-OK :done"
Description:
[n] = Is the output state of the relay terminal X2 under the connector panel cover
of the charging station (binary value).
0 = open
1 = closed
>=10 = Pulse output with the specified number of pulses (pulses / kWh)
and is stored in the EEPROM; reasonably usable up to 150.
The answer TCH-OK confirms only the receiving of the command and not the cor-
rectness of the value.
Values between 2 and 9 are not answered (reserved functions). Invalid values (e.g.
letters) are leading to a deactivation of the relay.
The correct reception can be verified using the proper report.
Note
The controllability is only available if the default function of the output is not activated via the DIP-
switch DSW1.2.
2.10UDP command “unlock”
UDP command:
unlock
Reply:
"TCH-OK :done"
Description:
For this command you have to stop the charging process first. For this, please use
the command „ena 0“. Afterwards you can unlock the socket.