smart-me

Recalculates the solar tariff prices of a billing property from the grid tariff prices, which is the yearly task after the energy supplier publishes new prices. By default the solar price becomes 80% of the grid price valid at the same time ('80% Pauschalmethode'). Shows a preview and changes nothing unless apply is true — always show the preview to the user and let them confirm before applying. Grid tariffs are never modified. After applying, the values must be recalculated in the smart-me portal ('Neu berechnen') before invoices reflect the new prices.

derive_solar_tariff_prices

WARNING: Changes the physical state of a device, e.g. switches a relay on or off. Only call this with explicit user intent, and only with an obisCode obtained from list_device_actions. For OnOffAction, value 1 switches on and 0 switches off. Requires an API key with the device.readswitch scope.

execute_device_action

Gets one load management group: its fuse limit, what it does when the connection to the cloud is lost, and its phase-switching settings.

get_load_management_group

Gets a tariff time by id: the weekday and time windows a peak tariff is limited to. The id comes from the ifThenActionId of a tariff in get_virtual_tariffs.

get_tariff_time

Gets the recent charging sessions of a station: when each started, how long it ran, how much energy went into the car and why it stopped.

get_charging_history

Gets the configuration of a charging station: name, current limits, authentication, load management group, display brightness and network details. The OCPP backend password is never returned — only whether one is set.

get_charging_station_settings

Gets what a charging station is doing right now: its state, the power and energy of a running session, the current it is allowed to draw, the load management group it belongs to, and the last warning or error. A station that has not reported for five minutes is shown as Offline.

get_charging_status

Gets consumption and cost per virtual tariff for one unit over a period. Takes the folder id of a UNIT (not the property); the tariffs of its parent property are applied. Dynamically priced tariffs report no price.

get_tariff_consumption

Gets the full details of a single smart-me device, including per-phase measurements, tariff counters and input/output states. Identify the device either by id or by serial number.

get_device

Gets the latest measured values of a device as OBIS-code/value pairs. OBIS codes are documented at http://wiki.smart-me.com/index.php/Obis_codes (e.g. 1-0:1.8.0*255 is the total imported active energy counter in Wh).

get_latest_values

Gets the invoice positions, demand charges, QR-invoice creditor data and VEWA settings of a billing property. This is the configuration around the tariffs; the tariffs themselves are read with get_virtual_tariffs.

get_billing_configuration

Gets the current virtual tariff counter readings per unit of a billing property, including each tariff's present share of active power. Use this to see how energy is currently being distributed across tariffs; use get_tariff_consumption for a period.

get_tariff_distribution

Answers which firmware the Pico charging stations of the account run: the communicationVersion of each station, which is the version of the station's own firmware and the one support asks for. Grouped by load management group. Also reports how far a running firmware update has got, which makes this the tool to poll while one is under way: leave a few minutes between calls, because one station takes between 5 and 30 minutes depending on its connection. An update is finished when progressPercent is 100 AND the station reports another communicationVersion than it had before. Pass versionsBefore, as start_pico_firmware_update returned it, and the answer says so as state 'Updated'; without it a station that never updated cannot be told from one that just finished. Every station of a group that was asked about is reported, not only the ones named, because a group carries one update at a time and any of its stations can be the one blocking it. Reads the connected account's own stations. Omit stationIds for all of them.

get_pico_firmware_status

Gets the folder tree of the account: how devices are organized into folders (e.g. buildings or sites). Meter nodes carry a meterSerialNumber that can be used with get_device to resolve the device.

get_folder_tree

Gets what a load management group is doing right now: power and current per phase, and how many of its stations are charging, paused, merely connected or online. The API allows ONE call per minute for this — do not poll it in a loop.

get_load_management_group_state

Gets the configured virtual tariffs of a billing property: name, type (Normal for grid tariffs, VZevSolar for solar, Battery), price per kWh, validity period and tariff number. Read this before changing a tariff — update_virtual_tariff needs the id of the tariff you want to change.

get_virtual_tariffs

Gets the values of a device as they were at (or just before) ONE point in time. Use it for a single consumption total: call it at the start and at the end of the period and subtract the counter readings. Do NOT call it repeatedly to build a series — get_value_history returns a whole series in one request and is far faster.

get_values_at

Gets a device's values over a period of time as a series at a fixed interval, in ONE request. Use this whenever a question covers more than a single moment: the last 7 days, a week, a month, how consumption or production developed, a trend, a comparison of two periods, or the figures behind a chart or table over time. It is also the tool for a quarter-hourly load profile (Lastgang, intervalMinutes 15), hourly values (60) and daily series (1440) — one call returns the whole series and is much faster than calling get_values_at once per point. Up to 1000 points per call; for a longer range, make consecutive calls rather than coarsening the interval. A large fine-grained range takes a while to answer, so request the period that is actually needed. Series over time need a smart-me Professional licence on the account. Whether the account holds one cannot be read beforehand, and when it is missing the error says so plainly, so the call is worth making rather than assumed unavailable.

get_value_history

Lists the VEWA cost periods of a billing property. A period is a billing window holding the building's total heating, cooling, hot water and cold water costs, which are then distributed across the units by floor area and measured consumption. Requires an access token with the user.readwrite scope.

list_vewa_cost_periods

Lists the billing properties (Liegenschaften) of the account with their residential and commercial units. A property is identified by its folder id, which every other billing tool takes as propertyFolderId.

list_billing_properties

Lists the Pico charging stations of the account with their latest readings. The id of a station is what every other charging tool takes; a station is also a meter, so the value tools work on it as well.

list_charging_stations

Discovers which actions a device supports (e.g. switching a relay on/off or setting an analog output). Use the returned obisCode with execute_device_action.

list_device_actions

Lists all smart-me devices (meters) of the authenticated account with their latest key readings. Use this first to discover device ids for the other tools.

list_devices

Lists the load management groups of the account. A group holds the charging stations that share one fuse and divides its current between them.

list_load_management_groups

Lists the configurations saved for this account, newest first, with the property each one describes. Read a single one with load_configuration.

list_configurations

Reads a saved configuration back. This only returns what was stored — it changes nothing in the smart-me cloud. Use it to compare against the current state, or as the input for rebuilding a property with create_billing_property, update_billing_property, update_billing_configuration, set_tariff_time and update_virtual_tariff. Check savedFromApi first: ids from another smart-me instance do not exist in this account and the meters have to be mapped by name or serial.

load_configuration

WARNING: Acts on a physical charging station. Only call with explicit user intent. Locks the charging cable into the station permanently, so it cannot be taken away. The station has to be online and the cable plugged in WITHOUT a car connected, otherwise the request is refused. Undoing this is done in the station's settings.

enable_fix_cable_lock

Moves meters and folders into other folders. Takes a LIST, so a whole set of meters is moved in one call — send one entry for a single move rather than calling this repeatedly. This organizes the tree; it does NOT decide whose invoice a meter's consumption lands on — that is what the meter assignments of update_billing_property do. Configuring a ZEV normally needs both. A failed entry does not stop the others.

move_to_folder

Renames meters and folders. Takes a LIST, so a whole set is renamed in one call — which is the normal case when a ZEV is set up from a customer's list. Send one entry for a single rename rather than calling this repeatedly. Each id may be a meter or a folder; the tool works out which. Only the name changes: the description, the folder type, the visualization and the place in the tree are read first and written back untouched. An entry whose name already matches is skipped and reported as such, and one that fails does not stop the others.

rename

Looks up meters by serial number and returns their ids, names and energy types. Use this to turn a customer's list — a CSV of serial numbers, apartments and tenants — into the ids every other tool takes, in one call instead of one per row. Serial numbers with no meter in the account are reported rather than skipped, so a typo in the list is found before anything is configured. Reads only.

resolve_meters

Saves the current configuration of a billing property under a name: the folders it lives in, its units with their meter shares and addresses, the invoice positions, the virtual tariffs and the peak-tariff time windows. Nothing in the smart-me cloud is changed. Use it before reconfiguring a ZEV, so the previous state can be compared or rebuilt, and to carry a configuration from the test to the production account. Saving the same name again replaces what was there.

save_configuration

WARNING: Acts on a physical charging station. Only call with explicit user intent. Sends one command to a station: 'UnlockConnector' releases the plug and stops any running charge — a car being charged right now stops charging; 'Reboot' restarts the station, which interrupts a running session; 'ShowMidMeterValuesOnDisplay' shows the calibrated meter reading on the display and changes nothing else. Check get_charging_status for a running session before the first two.

send_charging_station_command

WARNING: Decides how much current real charging stations may draw. Only call with explicit user intent. Sets the currently available current per phase for a load management group — the value a building's own measurement feeds in so that charging uses what the house is not using. It is a live figure, not a configuration: the stations follow it within seconds, and it is meant to be sent repeatedly by whatever measures the house.

set_load_management_dynamic_current

WARNING: Changes physical charging stations. Only call with explicit user intent. Sets what a Pico shows on its 32x32 LED matrix while no car is connected, replacing the image currently on it — the old one cannot be read back, so read idleImageUrl from get_charging_station_settings first if it should be kept. Takes a list of stationIds: the image is fetched once and sent to every station, which is the whole point of the list. PREFER imageUrl over imageData. imageData travels as base64 written token by token, so a 14 KB GIF is roughly 19'000 characters and a minute of generation, while a URL is twenty characters and the server fetches the bytes itself. To put an image that is already on one station onto others, pass that station's idleImageUrl as imageUrl — it is a public URL and costs nothing to reuse. For an image generated on the spot with no URL to give, render it small (32x32, few colours, few frames): the cost of imageData is linear in the file size and everything above 32x32 is discarded anyway. GIF, PNG, JPEG, BMP, WebP and TIFF are accepted, up to 4 MB; smart-me scales the image to 32x32 and converts it to a GIF, so only a GIF keeps its animation. It is an LED matrix: few colours and strong contrast read well, a logo or pictogram or pixel art far better than a photograph, whose detail and gradients are lost at 32x32 anyway. The station plays a GIF at 10 frames per second — 30 frames are three seconds — and holds about 150 KB, so a long loop can be too much for it even though the upload succeeded. A station has to be online, since the image is pushed to it right away. Requires an API key or token with the device.readswitch scope.

set_charging_station_idle_image

WARNING: Writes billing configuration. Updates name, dates and invoice flags of an existing VEWA cost period. The cost items themselves cannot be changed here — they are set when the period is created. Periods must not overlap. Requires the user.readwrite scope.

update_vewa_cost_period

WARNING: Changes billing configuration. Only call with explicit user intent. Updates a billing property: its name, and the units below it. Units are matched by their folder id — a known one is updated, an unknown one is created, and a unit that is simply not listed stays as it is. Units are never deleted, because they carry the invoice history. Fields left empty keep their stored value; passing meters for a unit replaces that unit's whole meter list.

update_billing_property

WARNING: Changes a physical charging station. Only call with explicit user intent. Changes the settings of a charging station. Fields left out keep their current value: the settings are read first and written back with the changes applied, because the API replaces the whole object. Lowering maxCurrentA below what the installation allows is the usual reason a car charges slowly, and raising it above the fuse is a hazard — take the limits from get_charging_station_settings.

update_charging_station_settings

WARNING: Changes billing configuration and therefore what tenants are charged. Only call with explicit user intent and confirm the values first. Writes the invoice positions, demand charges, QR-invoice creditor data and VEWA settings of a billing property. Anything omitted stays as it is; a list that IS given replaces the stored one completely, so read get_billing_configuration first and send back everything that should survive.

update_billing_configuration