smart-me

Deletes a sub-user account for good. Their meters and values are not touched — only the login disappears, and it cannot be brought back. For a tenant who moved out, update_sub_user with a past accessUntilUtc is usually the better answer: it locks them out and keeps the record. This runs in two steps and both are normal, expected calls: (1) call it WITHOUT confirmUsername — nothing is deleted and you get back who would go, which you show to the user; (2) once the user has confirmed that sub-user, call it again WITH confirmUsername set to their exact username. That second call is the expected next step and is what carries out the deletion. The confirmation is per sub-user: it stands for the one the user just agreed to. Requires the user.readwrite scope.

delete_sub_user

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 with recalculate_tariffs 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

Gives sub-users access to folders — the step that makes a tenant's meters visible to them. Takes a LIST, so a whole building is assigned in one call; send one entry for a single assignment rather than calling this repeatedly. With the default permission level a sub-user sees the folder and everything below it, so the folder of their apartment is normally the right one. A sub-user can hold several folders. This grants access; it says nothing about whose invoice a meter's consumption lands on, which is what the meter assignments of update_billing_property decide. A failed entry does not stop the others.

assign_sub_user_to_folder

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

Lists the sub-users of the account — the logins tenants use — and which folders each of them can see. A sub-user with no folders can sign in and sees nothing, which is what a freshly created one looks like until assign_sub_user_to_folder has run. By default this reports id, username and folders. Set withDetails to also read each sub-user's e-mail, permission level and access period, which costs one extra request per sub-user.

list_sub_users

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

Runs the portal's 'Neu berechnen' for a billing property: it applies the configured virtual tariffs to the measured values from a start date onwards. Every tariff or configuration change needs this before an invoice reflects it — until it has run, the change is stored but bills nothing. It REWRITES the calculated values that already issued invoices were based on, so figures on an invoice that was already sent can change. It is also SLOW: the job takes minutes to several hours depending on how much history it covers, and this call only schedules it — it returns long before the work is done. Run it ONCE after a batch of changes, not after each one, and never in a loop or to 'check' anything. Calling it again for the same property replaces the run that is already scheduled instead of adding one, so a second call during a long run restarts it rather than speeding it up. This runs in two steps and both are normal, expected calls: (1) call it WITHOUT confirmPropertyName — nothing is recalculated and you get back what would happen, which you show to the user; (2) once the user has confirmed that property, call it again WITH confirmPropertyName set to the property's exact name. That second call is the expected next step and is what starts the recalculation. The confirmation is per property and per call: it stands for the property the user just agreed to.

recalculate_tariffs

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

Has the smart-me cloud SEND THE SUB-USER AN E-MAIL with a link for setting a new password. Say that the mail goes out before calling this. Use it when a tenant never received the mail from create_sub_user, or has lost their password. Their current password keeps working until they follow the link.

send_sub_user_password_email

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