1.. _ocpp_interface:
2
3Open Charge Point Protocol (OCPP)
4#################################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13Open Charge Point Protocol (OCPP) is an application protocol for communication
14between Charge Points (Electric vehicle (EV) charging stations) and a central
15management system, also known as a charging station network. OCPP is a
16`standard <https://openchargealliance.org/protocols/open-charge-point-protocol/>`_
17defined by The Open Charge Alliance and goal is to offer a uniform solution for
18the method of communication between charge point and central system. With this
19protocol it is possible to connect any central system with any charge point,
20regardless of the vendor.
21
22Zephyr provides an OCPP Charge Point (CP) library built on top of websocket API
23with payload in json format. The library can be enabled with
24:kconfig:option:`CONFIG_OCPP` Kconfig option. Currently OCPP 1.6 with basic
25core profile is supported.
26
27OCPP charge point (CP) require a Central System (CS) server to connect, an open
28source SteVe server shall be setup locally for devlopment purpose, See
29`SteVe server <https://github.com/steve-community/steve/blob/master/README.md>`_
30for more information about the setup.
31
32The Zephyr OCPP CP library implements the following items:
33
34* engine to process socket connectivity and events
35* OCPP core functions to frame/parse payload, user notification for OCPP events,
36  heartbeat notification
37
38Sample usage
39************
40
41Init ocpp library with overall CP and CS information. Prior to init an OCPP
42library, a network interface should be ready using ethernet or wifi or modem.
43A filled CP, CS structure and user callback needs to be passed in ocpp_init.
44
45.. code-block:: c
46
47   static int user_notify_cb(ocpp_notify_reason_t reason,
48                             ocpp_io_value_t *io,
49                             void *user_data)
50   {
51
52        switch (reason) {
53        case OCPP_USR_GET_METER_VALUE:
54                ...
55                break;
56
57        case OCPP_USR_START_CHARGING:
58                ...
59                break;
60
61                ...
62                ...
63   }
64
65   /* OCPP configuration */
66   ocpp_cp_info_t cpi = { "basic", "zephyr", .num_of_con = 1};
67   ocpp_cs_info_t csi =  {"192.168.1.3",   /* ip address */
68                          "/steve/websocket/CentralSystemService/zephyr",
69                          8180,
70                          AF_INET};
71
72   ret = ocpp_init(&cpi, &csi, user_notify_cb, NULL);
73
74A unique session must open for each physical connector before any ocpp
75transcation API call.
76
77.. code-block:: c
78
79   ocpp_session_handle_t sh = NULL;
80   ret = ocpp_session_open(&sh);
81
82idtag is EV user's authentication token which should match with list on CS.
83Authorize request must call to ensure validity of idtag (if charging request
84originate from local CP) before start energy transfer to EV.
85
86.. code-block:: c
87
88    ocpp_auth_status_t status;
89    ret = ocpp_authorize(sh, idtag, &status, 500);
90
91On successful, authorization status is available in status.
92
93Apart from local CP, charging request may originate from CS is notified to user
94in callback with OCPP_USR_START_CHARGING, here authorize request call is
95optional. When the CS is ready to provide power to EV, a start transaction
96is notified to CS with meter reading and connector id using ocpp_start_transaction.
97
98.. code-block:: c
99
100   const int idcon = 1;
101   const int mval = 25; //meter reading in wh
102   ret = ocpp_start_transaction(sh, mval, idcon, 200);
103
104Once the start transaction is success, user callback is invoked to get meter
105readings from the library. callback should be not be hold for longer time.
106
107API Reference
108*************
109
110.. doxygengroup:: ocpp_api
111