GitLocker: The Coding Marketplace

Description:

pybluecurrent 0.0.3

pybluecurrent
Python client for BlueCurrent charge points.

Usage
Using the client is as simple as:
from pybluecurrent import BlueCurrentClient

client = BlueCurrentClient("your_username", "your_secret_password")

async with client:
charge_points = await client.get_charge_points()

transactions = client.get_transactions(charge_points[0]["evse_id"])

Methods
BlueCurrent exposes two APIs, a synchronous REST API as well as an asynchronous Websocket API.
As a result, the BlueCurrentClient also exposes synchronous as well as asynchronous methods:

Asynchronous

get_account
get_charge_cards
get_charge_points
get_charge_point_settings
get_grid_status
get_sustainability_status
set_plug_and_charge_charge_card
set_status

Synchronous

login
get_charge_point_status
get_contracts
get_grids
get_transactions
iterate_transactions

Asynchronous
The async methods can only be used when the websocket client is connected. For example:
client = BlueCurrentClient("your_username", "your_secret_password")
async with client:
result = await client.get_account()

Entering the async context will automatically login.
get_account - Get your account information.
async def get_account(self) -> dict[str, bool | str]

Returns
A dictionary describing your account:
{
"full_name": "Your Full Name",
"email": "your@email.address",
"login": "your@email.address",
"should_reset_password": False,
"developer_mode_enabled": False,
"tel": "",
"marketing_target": "bluecurrent",
"first_login_app": date(2020, 1, 1),
"hubspot_user_identity": "a_very_long_string"
}

get_charge_cards - Get your charge cards.
async def get_charge_cards(self) -> list[dict[str, date | int | str | None]]

Returns
A list of dictionaries, each representing a charge card:
{
"uid": "A1B2C3D4E5F6",
"id": "NL-ABC-123456-0",
"name": "My Charge Cards",
"customer_name": "Your Name",
"valid": 1,
"date_created": date(2023, 6, 27),
"date_modified": date(2023, 7, 11),
"date_became_invalid": None
}

get_charge_points - Get your charge points.
async def get_charge_points(self) -> list[dict[str, bool | dict | str]]

Returns
A list of dictionaries, each representing a charge card:
{
"evse_id": "BCU123456",
"name": "",
"model_type": "H:MOVE-C32T2",
"chargepoint_type": "HIDDEN",
"is_cable": True,
"public_charging": {"value": False, "permission": "write"},
"default_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
"customer_name": "Your Name", "valid": 1},
"preferred_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
"customer_name": "Your Name", "valid": 1},
"plug_and_charge_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
"customer_name": "Your Name", "valid": 1},
"tariff": {"tariff_id","NLBCUT58", "price_ex_vat": 0.2, "start_price_ex_vat": 0, "price_in_vat": 0.242,
"start_price_in_vat": 0, "currency": "EUR", "vat_percentage": 21},
"plug_and_charge_notification": False,
"plug_and_charge": {"value": True, "permission": "write"},
"led_interaction": {"value": False, "permission": "read"},
"publish_location": {"value": False, "permission": "write"},
"smart_charging": True,
"smart_charging_dynamic": True,
"activity": "available",
"location": {"x_coord": 50.1234, "y_coord": 5.01234, "street": "Europalaan", "housenumber": "100",
"zipcode": "3526KS", "city": "Utrecht", "country": "NL"},
"delayed_charging": {"value": False, "permission": "none"}
}

get_charge_point_settings - Get the settings of a charge point.
All the information returned by this endpoint is already included
in the response of get_charge_points.
async def get_charge_point_settings(self, evse_id: str) -> dict[str, bool | dict[str, Any] | str]

Arguments

evse_id: The ID of the charge point.

Returns
A dictionary describing the settings:
{
"evse_id": "BCU123456",
"plug_and_charge": {"value": True, "permission": "write"},
"public_charging": {"value": False, "permission": "write"},
"default_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
"customer_name": "Your Name", "valid": 1},
"preferred_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
"customer_name": "Your Name", "valid": 1},
"plug_and_charge_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
"customer_name": "Your Name", "valid": 1},
"smart_charging": True,
"smart_charging_dynamic": True,
"model_type": "H:MOVE-C32T2",
"is_cable": True,
"chargepoint_type": "HIDDEN",
"plug_and_charge_notification": False,
"led_intensity": {"value": 0, "permission": "none"},
"led_interaction": {"value": False, "permission": "none"}
}

get_grid_status - Get the grid status associated to a charge point.
async def get_grid_status(self, evse_id: str) -> dict[str, int | str]

Arguments

evse_id: The ID of the charge point.

Returns
A dictionary describing the actual grid current and maximum current in amps:
{
"id": "GRID-BCU123456",
"grid_actual_p1": 1,
"grid_actual_p2": 2,
"grid_actual_p3": 3,
"grid_max_install": 25,
"grid_max_reserved": 25
}

get_sustainability_status - Get statistics on the sustainability of all your charge points.
async def get_sustainability_status(self) -> dict[str, float | int]

Returns
A dictionary with two keys: {"trees": 1, "co2": 12.345}
set_plug_and_charge_charge_card - Set the charge card for plug-and-charge
async def set_plug_and_charge_charge_card(self, evse_id: str, uid: str | None = None) -> None

Sets the plug-and-charge card for the charge point. The uid must be a uid of one of your charge cards (see get_charge_cards) or None to use no charge card.
set_status - Enable or disable a charge point.
async def set_status(self, evse_id: str, enabled: bool) -> None

Arguments

evse_id: The ID of the charge point.
enabled: Boolean that indicates the desired status.

Synchronous
login - Log in
def login(self) -> None

This method does not do anything if the client is already logged in.
Connection to the websocket api (async with client) automatically logs in the client,
so this endpoint is not needed when using the async API.
get_charge_point_status - Get the status of a charge point.
def get_charge_point_status(self, evse_id: str) -> dict[str, datetime | float | int | str | None]

Arguments

evse_id: The ID of the charge point.

Returns
A dictionary with the chargepoint status:
{
"actual_p1": 0,
"actual_p2": 0,
"actual_p3": 0,
"activity": "available",
"actual_v1": 0,
"actual_v2": 0,
"actual_v3": 0,
"actual_kwh": 0,
"max_usage": 20,
"smartcharging_max_usage": 6,
"max_offline": 10,
"offline_since": "",
"start_datetime": datetime(2023, 7, 24, 15, 25, 33),
"stop_datetime": datetime(2023, 7, 26, 7, 48, 40),
"total_cost": 9.93,
"vehicle_status": "A",
"evse_id": "BCU123456",
}

get_contracts - Get your contracts.
def get_contracts(self) -> list[dict[str, str]]

Returns
A list of dictionaries, each representing a contract:
[
{
"contract_id": "BCU12345678",
"contact_email": "your@email.address",
"subscription_type": "BASIS",
"beneficiary_name": "Your Name",
"iban_beneficiary": "NL00ABCD0123456789"
}
]

get_grids - Get your grid connections.
def get_grids(self) -> list[dict[str, bool | dict[str, str] | str]]

Returns
A list of dictionaries, each representing a grid:
[
{
"address": {"street": "Street Name", "housenumber": "1", "postal_code": "1234AB",
"city": "Amsterdam", "country": "NL", "region": ""},
"smart_charging": True,
"id": "GRID-BCU123456"
}
]

get_transactions - Get a list of transactions.
def get_transactions(
self, evse_id: str, newest_first: bool = True, page: int = 1
) -> dict[str, int | list[dict[str, Any]]]

Arguments

evse_id: The ID of the charge point.
newest_first: If True, start with the most recent transaction. Defaults to True.
page: Page number to get. Defaults to 1.

Returns
A dictionary like this:
{
"current_page": 1,
"next_page": 2, # This is None when there is no next page.
"max_per_page": 25,
"total_pages": 8,
"transactions: [
{
"transaction_id": 12345678,
"chargepoint_id": "BCU123456",
"chargepoint_type": "HIDDEN",
"evse_name": "Charge Point Name",
"started_at": datetime(2023, 7, 1, 12, 34, 56),
"end_time": datetime(2023, 7, 1, 14, 0, 0),
"kwh": 12.34,
"card_id": "NL-ABC-123456-0",
"card_name": "Card Name",
"total_costs": 5.97,
"total_costs_ex_vat": 4.93,
"vat": 21,
"currency": "EUR"
},
...
]
}

iterate_transactions - Iterate through your transactions
def iterate_transactions(self, evse_id: str, newest_first: bool = True) -> Iterable[dict[str, Any]]

Arguments

evse_id: The ID of the charge point.
newest_first: If True, start with the most recent transaction. Defaults to True.

Returns
An iterable of dictionaries describing the transactions. Each dictionary looks like this:
{
"transaction_id": 12345678,
"chargepoint_id": "BCU123456",
"chargepoint_type": "HIDDEN",
"evse_name": "Charge Point Name",
"started_at": datetime(2023, 7, 1, 12, 34, 56),
"end_time": datetime(2023, 7, 1, 14, 0, 0),
"kwh": 12.34,
"card_id": "NL-ABC-123456-0",
"card_name": "Card Name",
"total_costs": 5.97,
"total_costs_ex_vat": 4.93,
"vat": 21,
"currency": "EUR"
}