search

tiramiseb / python-openevse

Python library for the OpenEVSE RAPI protocol
MIT License
23 stars 10 forks source link

readme

=============== Python-OpenEVSE

This library helps communicating with OpenEVSE boards, using the RAPI protocol.

What is OpenEVSE ?

EVSE stands for Electrical Vehicle Supply Equipment. An EVSE is a charging station for electrical vehicles.

OpenEVSE is an Open Hardware EVSE, allowing people to build their own EVSEs.

OpenEVSE is not a finished product to be used by an end-user.

What is RAPI ?

RAPI stands for "Remote API", allowing remote hardware to control the OpenEVSE board using a serial port, with the FTDI/UART pins on the board.

The default baudrate is 115200, according to OpenEVSE sources (open_evse.h).

How to install this library ?

::

pip install python-openevse

How to use this library ?

See the inline documentation::

>>> import openevse
>>> help(openevse)

License

MIT <http://opensource.org/licenses/MIT>_

In short : do what you want but keep our names in the resulting software.

As of Feb 5, 2019, Vitaly Greck has taken over the management of this project.

Please, if you improve it, contribute back. Thanks ! :)

The low-level API

Documentation on the RAPI protocol v1.0.3, from rapi_proc.h::

 **** RAPI protocol ****

Fx - function
Sx - set parameter
Gx - get parameter

command formats
1. with XOR checksum (recommended)
$cc pp pp ...^xk\r
2. with additive checksum (legacy)
$cc pp pp ...*ck\r
3. no checksum (FOR TESTING ONLY! DON'T USE FOR APPS)
$cc pp pp ...\r

\r = carriage return = 13d = 0x0D
cc = 2-letter command
pp = parameters
xk = 2-hex-digit checksum - 8-bit XOR of all characters before '^'
ck = 2-hex-digit checksum - 8-bit sum of all characters before '*'

response format
$OK [optional parameters]\r - success

$NK [optional parameters]\r - failure

asynchronous messages
$ST state\r - EVSE state transition - sent whenever EVSE state changes
 state: EVSE_STATE_xxx

commands

FB color - set LCD backlight color
colors:
 OFF 0
 RED 1
 YELLOW 3
 GREEN 2
 TEAL 6
 BLUE 4
 VIOLET 5
 WHITE 7 

 $FB 7*03 - set backlight to white
FD - disable EVSE
 $FD*AE
FE - enable EVSE
 $FE*AF
FP x y text - print text on lcd display
FR - reset EVSE
 $FR*BC
FS - sleep EVSE
 $FS*BD

S0 0|1 - set LCD type
 $S0 0*F7 = monochrome backlight
 $S0 1*F8 = RGB backlight
S1 yr mo day hr min sec - set clock (RTC) yr=2-digit year
S2 0|1 - disable/enable ammeter calibration mode - ammeter is read even when not charging
 $S2 0*F9
 $S2 1*FA
S3 cnt - set charge time limit to cnt*15 minutes (0=disable, max=255)
SA currentscalefactor currentoffset - set ammeter settings
SC amps - set current capacity
SD 0|1 - disable/enable diode check
 $SD 0*0B
 $SD 1*0C
SE 0|1 - disable/enable command echo
 $SE 0*0C
 $SE 1*0D
 use this for interactive terminal sessions with RAPI.
 RAPI will echo back characters as they are typed, and add a <LF> character
 after its replies
SF 0|1 - disable/enable GFI self test
 $SF 0*0D
 $SF 1*0E
SG 0|1 - disable/enable ground check
 $SG 0*0E
 $SG 1*0F
SH kWh - set cHarge limit to kWh
SK - set accumulated Wh (v1.0.3+)
 $SK 0*12 - set accumulated Wh to 0
SL 1|2|A  - set service level L1/L2/Auto
 $SL 1*14
 $SL 2*15
 $SL A*24
SM voltscalefactor voltoffset - set voltMeter settings
SR 0|1 - disable/enable stuck relay check
 $SR 0*19
 $SR 1*1A
SS 0|1 - disable/enable GFI self-test
 $SS 0*1A
 $SS 1*1B
ST starthr startmin endhr endmin - set timer
 $ST 0 0 0 0*0B - cancel timer
SV 0|1 - disable/enable vent required
 $SV 0*1D
 $SV 1*1E

G3 - get time limit
 response: OK cnt
 cnt*15 = minutes
        = 0 = no time limit
GA - get ammeter settings
 response: OK currentscalefactor currentoffset
 $GA*AC
GC - get current capacity range in amps
 response: OK minamps maxamps
 $GC*AE
GE - get settings
 response: OK amps(decimal) flags(hex)
 $GE*B0
GF - get fault counters
 response: OK gfitripcnt nogndtripcnt stuckrelaytripcnt (all values hex)
 $GF*B1
GG - get charging current and voltage
 response: OK milliamps millivolts
 AMMETER must be defined in order to get amps, otherwise returns 0 amps
 VOLTMETER must be defined in order to get voltage, otherwise returns 0 volts
 $GG*B2
GH - get cHarge limit
 response: OK kWh
 kWh = 0 = no charge limit
GM - get voltMeter settings
 response: OK voltcalefactor voltoffset
 $GM^2E
GP - get temPerature (v1.0.3+)
 $GP*BB
 response: OK ds3231temp mcp9808temp tmp007temp
 ds3231temp - temperature from DS3231 RTC
 mcp9808temp - temperature from MCP9808
 tmp007temp - temperature from TMP007
 all temperatures are in 10th's of a degree Celcius
 if any temperature sensor is not installed, its return value will be 0
GS - get state
 response: OK state elapsed
 state: EVSE_STATE_xxx
 elapsed: elapsed charge time in seconds (valid only when in state C)
 $GS*BE
GT - get time (RTC)
 response OK yr mo day hr min sec       yr=2-digit year
 $GT*BF
GU - get energy usage (v1.0.3+)
 $GU*C0
 response OK Wattseconds Whacc
 Wattseconds - Watt-seconds used this charging session, note you'll divide Wattseconds by 3600 to get Wh
 Whacc - total Wh accumulated over all charging sessions, note you'll divide Wh by 1000 to get kWh
GV - get version
 response: OK firmware_version protocol_version
 $GV*C1

Relation between low-level API commands and Python-OpenEVSE

Some links to OpenEVSE