evbilling - produce EV charger submeter bills for PG&E BEV-1 rate schedule
evbilling [-h | --help] [--autoblock | --no-autoblock] [--copybill | --no-copybill] [-d | --debug | --no-debug] [--dump | --no-dump] [--fixocr | --no-fixocr] [--forceocr | --no-forceocr] [--pages PAGES] [--print | --no-print] [-q | --quiet | --no-quiet] [--showocr | --no-showocr] [--submeter | --no-submeter] [-v | --version | --no-version] [--zip | --no-zip] FILE [DIRECTORY]
evbilling produces bills for Electric Vehicle (EV) chargers connected to the EV power panel at The Palace at Washington Square condominium in San Francisco, CA. The EV power panel is equipped with an Emporia Vue 3 energy monitor. Input is a Pacific Gas & Electric (PG&E) BEV-1 rate schedule bill in PDF format downloaded from pge.com.
The evbilling program:
- performs Optical Character Recognition (OCR) on a Pacific Gas & Electric/CleanPowerSF PDF bill to obtain billing periods, rates, and charges;
- writes an OCR sidecar text file, which can be edited if necessary to correct OCR errors;
- downloads hourly usage data for the billing period for the individual EV chargers from the Emporia Vue server; and
- writes EV charger PDF and plain text submeter bill files, accounting for rate changes and varying Time-Of-Use (TOU) rates.
evbilling writes the following files to a directory named yyyy-mm-dd that it creates in the current directory or in the directory specified by the DIRECTORY argument, where yyyy-mm-dd is the statement date of the bill file (see ARGUMENTS below):
- nnnncustbillmmddyyyy.pdf -- a copy of the PG&E bill file unless --no-copybill is specified.
- nnnncustbillmmddyyyy-OCR.txt -- the OCR result sidecar text file for the PG&E bill.
- nnnncustbillmmddyyyy.txt -- a plain text version of the PG&E bill, created if OCR completes without errors.
- nnnncustbillmmddyyyy-circuit.pdf -- a PDF submeter bill for each circuit connected to the EV power panel. The circuit names configured with the Emporia Vue app have the format PWS-uuu-Pnn, where uuu is the Owner's Unit number and nn is the EV charger parking space number.
- nnnncustbillmmddyyyy-circuit.txt -- a plain text submeter bill for each circuit connected to the EV power panel.
- nnnncustbillmmddyyyy-circuit.csv -- a CSV (Comma Separated Values) file of the raw usage data, formatted as a day-by-hour matrix, for each circuit connected to the EV power panel unless --no-dump is specified.
- nnnncustbillmmddyyyy.zip -- a .zip file containing all PDF bill files unless --no-zip is specified.
evbilling also writes a log file named evbilling.log to the current directory or to the directory specified by the DIRECTORY argument.
-h, --help : Print a help message and exit.
--autoblock, --no-autoblock : Automatically locate OCR text blocks; default --autoblock.
--copybill, --no-copybill : Copy the PG&E bill PDF file to the output directory; default --copybill.
-d, --debug, --no-debug : Log debugging information; default --no-debug.
--dump, --no-dump : Dump hourly usage data, formatted as a day-by-hour matrix, to a .csv file; default --dump.
--fixocr, --no-fixocr : Fix obvious OCR errors; default --fixocr.
--forceocr, --no-forceocr : Force PDF Optical Character Recognition (OCR); default --no-forceocr.
--pages ij : Two single-digit page numbers, i is the Details of PG&E Electric Delivery Charges page number and j is the Details of CleanPowerSF Electric Generation Charges page number; default: 34.
--print, --no-print
: Print PG&E bill OCR text to stdout; default: --no-print.
-q, --quiet, --no-quiet
: Do not print INFO, WARNING, ERROR, or CRITICAL messages to stderr; default --no-quiet.
--showocr, --no-showocr : Show OCR result; implies --forceocr; default --no-showocr.
--submeter, --no-submeter : Write PDF submeter bills; default --submeter.
-v, --version, --no-version : Display the version number and exit.
--zip, --no-zip : Write all PDF bill files to nnnncustbillmmddyyyy.zip file; default --zip.
FILE : The PG&E PDF bill file to be processed. FILE must have the format nnnncustbillmmddyyyy.pdf, where nnnn is the last four digits of the PG&E account number and mmddyyyy is the PG&E bill statement date.
DIRECTORY : Output directory, default current working directory.
Edit the evsettings.py module to change the settings used by evbilling.
CONTACT_EMAIL = 'pws.ev.energy@gmail.com'
"""Email address to appear in submeter bill footer."""
EV_SYSTEM = 'emporiavue'
EV_USERNAME = 'pws.ev.energy@gmail.com'
"""keyring arguments for the Emporia Vue server."""
These settings are used to retrieve the Emporia Vue server account password from the PC's keyring. Set the Emporia Vue password with the command:
keyring set "EV_SYSTEM" "EV_USERNAME"
For example:
keyring set "emporiavue" "pws.ev.energy@gmail.com"
EVSE_kW_RATINGS = {
'PWS-304-P05':120*16/1000, # NEMA 5-15R, 3030-PSE-16-7.7C-AS charging cable, nominal
'PWS-404-P06':1.46, # NEMA 5-!5R, Toyota G9060-47130 charging cable, measured June, 2024
'PWS-502-P07':208*40/1000, # Tesla 80A, nominal
'PWS-405-P14':208*48/1000, # Tesla Gen3, nominal
'PWS-403-P20':208*40/1000, # Tesla 80A, nominal
}
"""EVSE (Electric Vehicle Service Equipment) power ratings in kW."""
The PG&E BEV-1 rate schedule includes a subscription (a.k.a demand) charge based on a measurement of the maximum kW power usage in any single 15-minute period during a monthly billing cycle. The subscription charge is purchased in blocks of 10 kW, and the charge is apportioned to the EV chargers based on their kW power ratings.
The EV charger names (keys) in the EVSE_kW_RATING setting must match the
circuit names configured in the Emporia Vue application, and the corresponding
values are the EV charger power ratings in kW. This setting must be updated
whenever EV chargers are connected, disconnected, or replaced. Initially, the
nominal charger power rating can be set, but should be updated to the actual
value as measured by the Emporia Vue application.
NB: Whenever the load on the EV power panel changes, contact the PG&E Solar department at 877-743-4112 and ask to be transferred to Solar/EV Business department to adjust the number of 10 kW blocks and request a grace period. From PG&E Electric Schedule BEV, SPECIAL CONDITIONS, 7. GRACE PERIOD:
GRACE PERIOD: A grace period is a period of three (3) billing cycles, each with a minimum of 27 days, in which a BEV customer is not subject to overage fees (see “Special Conditions” section, item 8) associated with exceeding the customer’s monthly pre-defined kW subscription. A grace period is triggered under the following two conditions:
- Customer Enrollment: A grace period is triggered when a customer enrolls in a BEV rate.
- Addition of Electrical Vehicle Service Equipment (EVSE): After a customer is enrolled in BEV rate, a second qualifying event for grace periods is if an existing customer enrolled on the BEV rate (either BEV-1 or BEV-2 rate option) adds additional charging infrastructure that increases load. In this case, a customer must notify PG&E that they have increased the amount of EVSE infrastructure behind the meter, which will then trigger a grace period.
Failure to notify PG&E can incur an OVERAGE FEE, as described in PG&E Electric Schedule BEV, SPECIAL CONDITIONS, 8. OVERAGE/OVERAGE FEE.
CPSF_RATE_CHANGE = '7/1'
"""Date of CleanPowerSF annual rate change."""
TOU_HOURS = {Tou.SUPER_OFF_PEAK: [range(9, 12+2)],
Tou.PEAK: [range(12+4, 12+9)],
}
"""Time-Of-Use hourly ranges."""
The TOU_HOURS table defines the hours to which various Time-Of-Use (TOU) $/kWh
rates apply. The table associates TOU names (keys) with corresponding lists of
hourly ranges (values). For example, the entry:
Tou.SUPER_OFF_PEAK: [range(9, 12+2)],
associates the "Super Off Peak" TOU period with the range of hours from 9 AM (9) to 2 PM (12+2).
Tou.OFF_PEAK is set automatically to be all hours other than those defined in
TOU_HOURS.
Set FONTCONFIG_PATH to C:\Users\User\.config\fontconfig in
the User environment.
C:\Users\User\.config\fontconfig should include a fonts.conf file, e.g.:
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
<dir>C:/Windows/Fonts</dir>
<cachedir>C:/Users/Your User Name Here/AppData/Local/fontconfig/cache</cachedir>
<config>
<rescan>
<int>30</int>
</rescan>
</config>
</fontconfig>Run the following command to build font information cache files:
fc-cache -fv
Install python 3.12 or later version.
Install pipx:
pip install pipx
Install keyring:
pipx install keyring
pipx install path\evbilling-version-py3-none-any.whl
For example:
pipx install path\evbilling-0.1.5-py3-none-any.whl
Alternatively, install evbilling from a .tar.gz package file:
pipx install path\evbilling-version.tar.gz
For example:
pipx install path\evbilling-0.1.5-.tar.gz
The evtariffs command downloads the PG&E tariff PDF files required by evbilling and prepends the tariff effective date to the PDF filename:
usage: evtariffs.py [-h] [-d | --debug | --no-debug] [-q | --quiet | --no-quiet] [-v | --version | --no-version] [DIRECTORY]
Download PG&E BEV tariffs and order by effective date
positional arguments:
DIRECTORY Output directory; default "C:\Users\<Username>\.evbilling\tariffs"
options:
-h, --help show this help message and exit
-d, --debug, --no-debug
Log debug info; default --no-debug
-q, --quiet, --no-quiet
Do not print verbose output; default --quiet
-v, --version, --no-version
Display the version number and exit
Schedule the evtariffs command to be run at least weekly so that newly published tariffs are not missed.
Note: The DIRECTORY argument is used only for testing since evbilling
expects tariffs to be found in the default directory, and evtariffs writes a
log file, evtariffs.log, to the tariffs directory. To store the tariffs
in a different directory, create a link to it named tariffs in the default
.evbilling directory.
Optionally, runevbilling can be configured for use with the Windows File Explorer Open with ... menu to allow evbilling to be run on a PG&E PDF bill file without needing to launch cmd and enter a command.
To configure runevbilling:
- Browse with Windows File Explorer to the folder containing the PG&E PDF bill file to be processed.
- Right-click on the bill file and choose Open with -> Choose another app.
- Scroll to the bottom and choose More apps.
- Scroll to the bottom and choose Look for another app on this PC.
- Browse to
C:\Users\Username\.local\bin. - Open runevbilling.exe.
This will run evbilling on the bill file and add runevbilling.exe to the Choose another app menu for future use.
Most options are intended for testing and debugging. After downloading a PG&E bill named e.g. 2318custbill06132024.pdf, the command:
evbilling 2318custbill06132024.pdf
will create a subdirectory named 2024-06-13 to which it will write all files as described earlier, including the submeter PDF bill files to be sent to the Owners.
OCR is not 100% accurate, so evbilling may fail because it cannot find the keywords it requires, or dates are inconsistent, or charges are missing or do not reconcile, in which case it reports problems and stops. It is then necessary to manually correct the OCR sidecar file and rerun the evbilling command. In this example, the sidecar file would be named 2318custbill06132024-OCR.txt.
When run, evbilling checks for an existing sidecar file and uses it instead of performing OCR on the PG&E bill. It may be necessary to correct and rerun the command repeatedly until all OCR errors have been corrected. For example, suppose evbilling fails:
evbilling 2318custbill07162024.pdf
2024-07-27 15:42:13 - CRITICAL - Missing 1011044609 PG&E charges: {'Franchise Fee Surcharge'}.; exiting.
The 2318custbill07162024-OCR.txt file may then contain the excerpt:
=== Page 3 details ===
Details of PG&E Electric Delivery Charges
06/08/2024 - 07/09/2024 (32 billing days)
Service For: 1731 POWELL ST HSE EV CHARGER
Service Agreement ID: 3758116729
Rate Schedule: BEV1 Bus Low Use EV
06/08/2024 - 06/30/2024
Subscription Charges 1
Subscription Level (10kW/block) 10 blocks @ 0.7188 month @ $12.41 $89.20
Overage Fees 0 kW @ $2.48000 0.00
Energy Charges
Peak 1.904500 kWh @ $0.40040 0.12
Off Peak 17.028000 kWh @ $0.20938 3.55
Super Off Peak 2.518500 kWh @ $0.18173 0.46
Generation Credit -3.14
Power Charge Indifference Adjustment 0.17
Franchise e Fee Surcharge 0.02
San Francisco Utility Users' Tax (7.500%) 6.82
SF Prop C Tax Surcharge 0.90
The problem is the "e" between "Franchise" and "Fee".* After editing 2318custbill07162024-OCR.txt with e.g. Notepad to remove the 'e', evbilling is rerun and fails again:
2024-07-27 15:44:41 - ERROR - Invalid 1011044609 PG&E charge: Peak 1.804500 kWh @ $0.40040 $ 0.12
2024-07-27 15:44:41 - ERROR - Calculated PG&E total charges $135.96 not equal to OCR total charges $136.56
2024-07-27 15:44:41 - ERROR - 2 error(s) found while processing 2318custbill07162024.pdf.
2024-07-27 15:44:41 - CRITICAL - For details see log file: Testing\evbilling.log.; exiting.
Comparing the invalid PG&E charge to the original bill shows that the Peak energy charge should be $0.72 instead of $0.12. After correcting this error, evbilling runs without errors.
Even if evbilling runs without errors, the plain text version of the PG&E bill, which in this example would be named 2318custbill06132024.txt, should be compared to the downloaded bill to assure accuracy.
*OCR actually makes this type of error, but the evbilling --fixocr option corrects these "obvious" errors before writing the sidecar file.
A submeter bill consists of three pages, described in the following sections.
The header of every page contains the submeter Account name, the Statement Date from the corresponding PG&E main bill, and the Due Date, which is the first day of the month after the Statement Date.
The footer of every page has the contact email address and the date on which the submeter bill was produced.
Charger Power Rating : Charger power rating in kW, obtained from evsettings.py.
Total Usage : Total charger energy usage for the billing period in kWh, as measured by the submeter.
PG&E Electric Delivery Charges : Total PG&E Electric Delivery Charges from page 2.
CleanPowerSF Electric Generation Charges : Total CleanPowerSF Electric Generation Charges from page 3.
Metering Difference Adjustment : Adjustment for the difference between the PG&E panel meter reading and the sum of the individual submeter readings. Formula:
[(PG&E main bill Total Amount Due) - sum(All submeter PG&E and CleanPowerSF charges)]
*(Submeter Total Usage)
-------------------------------------------------------------------------------------
(PG&E main bill Total Usage)
Total Amount Due : Sum of submeter PG&E Electric Delivery Charges, CleanPowerSF Electric Generation Charges, and the Metering Difference Adjustment.
Effective Rate : (Total Amount Due/Total Usage)
Cost Breakdown Chart : Pie chart showing cost and percentage of the submeter bill for Peak kWh, Off Peak kWh, Super Off Peak kWh, Subscription Charge and any Overage Fees, and Taxes & Fees for the billing period.
Energy Usage Cost Chart : Stacked bar chart showing Peak kWh cost, Off Peak kWh cost, Super Off Peak kWh cost, and Subscription cost for each day of the billing period. All costs include taxes & fees, and all energy (kWh) usage costs include the Metering Difference Adjustment.
Monthly kWh Usage Chart : Stacked bar chart showing Peak kWh, Off Peak kWh, and Super Off Peak kWh energy usage for the current month and the previous 12 months.
Subscription Level : Cost based on the Charger Power Rating from page 1. Formula:
(Charger Power Rating in kW)
(Number 10kW blocks)*Months*Rate*------------------------------------
sum(All Charger Power Ratings in kW)
Overage Fees : Fees charged for exceeding the Subscription Level kW peak power demand. Formula:
(PG&E main bill Overage Fees charge)*(Charger Power Rating in kW)
-----------------------------------------------------------------
sum(All Charger Power Ratings in kW)
PG&E Energy Charges : Peak, Off Peak, and Super Off Peak kWh costs based on submeter kWh measurements.
PG&E Energy Credits : Credit rates are obtained from the BEV-1 tariff in effect during the billing period.
Peak, Off Peak, and Super Off Peak generation credits : Credits due to electric generation by CleanPowerSF instead of PG&E. Formula:
-(Generation Credit rate $/kWh)*(Peak, Off Peak, or Super Off Peak kWh)
Bundled Power Charge Indifference Adjustment (PCIA) credit : Credit against the Vintaged Power Charge Indifference Adjustment. Formula:
(Bundled Power Charge Indifference Adjustment rate $/kWh)*(Submeter Total Usage kWh)
Total Generation Credit : Sum of the PG&E Energy Credits.
Power Charge Indifference Adjustment : Addition to PG&E costs to compensate for PG&E generation assets stranded by CleanPowerSF customers. The PCIA is determined by the "vintage" year that a customer started to obtain power from CleanPowerSF. Formula:
(PG&E main bill Power Charge Indifference Adjustment charge)
------------------------------------------------------------*(Submeter Total Usage kWh)
(PG&E main bill Total Usage kWh)
Net Charges : Sum of Subscription Level charge, Subscription Overage Fees, PG&E Energy Charges, Total Generation Credit, and Power Charge Indifference Adjustment.
Franchise Fee Surcharge : Collect the fee PG&E pays to San Francisco for use of city streets to transmit, distribute, and supply electricity. Formula:
(PG&E main bill Franchise Fee Surcharge)
----------------------------------------*(Submeter Total Usage kWh)
(PG&E main bill Total Usage kWh)
San Francisco Utility Users' Tax : Collect the tax PG&E pays to San Francisco for non-residential electricity consumption. Formula:
(PG&E main bill San Francisco Utility Users' Tax)
----------------------------------------*(Submeter Net Charges)
(PG&E main bill Net Charges)
SF Prop C Tax Surcharge : Collect the tax PG&E pays to San Francisco to fund its homelessness programs. Formula:
(PG&E main bill SF Prop C Tax Surcharge)
----------------------------------------*(Submeter Net Charges)
(PG&E main bill Net Charges)
CleanPowerSF Energy Charges : Peak, Off Peak, and Super Off Peak kWh costs based on submeter kWh measurements.
Net Charges : Sum of CleanPowerSF Energy Charges.
Local Utility Users Tax : Collect the tax CleanPowerSF pays to San Francisco for non-residential electricity consumption. Formula:
(CleanPowerSF main bill Local Utility Users' Tax)
-------------------------------------------------*(Submeter Net Charges)
(CleanPowerSF main bill Net Charges)
Energy Commission Surcharge : Collect the tax CleanPowerSF pays to California for consumption of electrical energy. Formula:
(CleanPowerSF main bill Energy Commission Surcharge)
----------------------------------------------------*(Submeter Net Charges)
(CleanPowerSF main bill Net Charges)
CleanPowerSF changes rates annually on July 1. Unlike PG&E rates changes, these are combined in a single rate period on the PG&E bill, which evbilling splits into two rate periods, the first ending on June 30 and the second beginning on July 1, assuming that the first and second rates listed for each TOU period are the rates for the first and second rate periods, respectively. If rates are missing due to no usage during a TOU period, evbilling stops and the missing rates must looked up from previous bills or on CleanPowerSF Commercial Rates, B-EV-1, p.5 and manually entered in the sidecar file.
- Emporia Energy Help Center
- Emporia Account Login
- PG&E Electric Schedule BEV
- Commercial Business Electric Vehicle (BEV) Rates
- CleanPowerSF Commercial Rates, B-EV-1, p.5
- SF Franchise Fee Surcharge
- San Francisco Utility Users' Tax (7.500%)
- SF Prop C Tax Surcharge
- Energy Commission Surcharge
- PyEmVue -- Unofficial library for interacting with the Emporia Vue energy monitor
- docTR: Document Text Recognition
Keith Gorlen
gorlen@comcast.net
Copyright (c) 2024 Keith Gorlen
All Rights Reserved