rscp-client v0.1.2

rscp-client - a NodeJS client library for E3/DC devices using the RSCP protocol

Query and control your E3/DC device using the RSCP protocol. A low-level and a high-level interface are provided. The low-level interface is powerful but requires knowledge of the individual RSCP tags. The high-level interface is easier to use, but only a limited subset of the functionality is supported.

Usage

A simple session to query the device's serial number using the high-level interface could look like this:

import { RscpClient } from 'rscp-client';

const client = await RscpClient.connect({
  host: '192.168.227.220', // IP address (or hostname) of the E3/DC device
  aes_password: 'rscp_password', // RSCP password as configured in the E3/DC device
});

const auth_level = await client.authenticate(
  'portaluser@example.com', // user name as used in E3/DC portal
  'portal_password', // associated password
);

const serial_number = await client.getSerialNumber();

await client.close();

The auth_level is either 0, if the authentication failed, or 10, if the authentication was successful for a normal user. (Users with advanced priviledges will get an even higher auth_level.)

The same could be achieved using the low level interface:

import {
  RscpClient,
  RscpTag,
  RscpContainerValue,
  RscpNoneValue,
  RscpStringValue,
} from 'rscp-client';

const client = await RscpClient.connect({
  host: '192.168.227.220', // IP address (or hostname) of the E3/DC device
  aes_password: 'rscp_password', // RSCP password as configured in the E3/DC device
});

const auth_result = await client.send([
  new RscpContainerValue(RscpTag.RSCP_REQ_AUTHENTICATION, [
    new RscpStringValue(RscpTag.RSCP_AUTHENTICATION_USER, 'portaluser@example.com'),
    new RscpStringValue(RscpTag.RSCP_AUTHENTICATION_PASSWORD, 'portal_password'),
  ]),
]);
const auth_level = auth_result[0].value;

const serial_number_result = await client.send([
  new RscpNoneValue(RscpTag.INFO_REQ_SERIAL_NUMBER),
]);
const serial_number = serial_number_result[0].value;

await client.close();

Note that the raw results obtained from client.send should be checked to have the expected length, tag, and type; see below.

High-level and low-level operations can be mixed freely, so that supported operations can (and should) use the high-level interface, while operations not (yet) supported can be accessed using the low-level interface.

Reference

Connection management

RscpClient.connect({ host: string, aes_password: string }): Promise<RscpClient>

Connects to the E3/DC device host (IP address or hostname) and uses aes_password (configured as RSCP password in the E3/DC device) for encryption. Returns a promise that resolves to an RscpClient instance or rejects if no connection could be established. Note that a wrong aes_password will not result in an error at this stage as no data is actually transferred, yet.

client.close(): Promise<void>

Closes the connection. No requests are possbile after calling close. Note that not calling close will keep the node process from terminating.

High-level requests

client.authenticate(user: string, password: string): Promise<number>

Send an autnetication request using the given user name and password. (The same as used to log in to the portal.) Resolves to the obtained user level: 0 for failed authentication, 10 for normal user, higher numbers for users with elevated privileges (e.g. installer).

client.getPVPower(): Promise<number>

Requests and resolves to the power (in Watt) currently delivered by the PV.

client.getBatteryChargePower(): Promise<number>

Requests and resolves to the power (in Watt) the battery in currently charged at. Negative values indicate discharging.

client.getHomeConsumptionPower(): Promise<number>

Requests and resolves to the power (in Watt) currently consumed, excluding wallboxes.

client.getFromGridPower(): Promise<number>

Requests and resolves to the power (in Watt) currently withdrawn from the grid. Negative values indicate feeding into the grid.

client.getAdditionalPower(): Promise<number>

Requests and resolves to the power (in Watt) currently delivered by additional sources.

client.getAutarkyPercentage(): Promise<number>

Requests and resolves to current autarky level in percent.

client.getSelfConsumptionPercentage(): Promise<number>

Requests and resolves to current percentage of produced power consumed instead of fed into the grid.

client.getBatterySOCPercentage(): Promise<number>

Requests and resolves to current battery state of charge in percent.

client.getWallboxPower(): Promise<number>

Requests and resolves to the power (in Watt) currently delivered to the wallbox.

client.getWallboxSolarPower(): Promise<number>

Requests and resolves to solar part of the power (in Watt) currently delivered to the wallbox.

client.getSerialNumber(): Promise<string>

Requests and resolves to the device's serial number.

client.getProductionDate(): Promise<string>

Requests and resolves to the device's production date.

client.getModuleSoftwareVersions(): Promise<{ module: string; version: string }[]>

Requests and resolves to the versions of the device's individual software modules.

client.getIPAddress(): Promise<string>

Requests and resolves to the device's IP address, which should usually equal the IP address used when connecting.

client.getSubnetMask(): Promise<string>

Requests and resolves to the device's subnet mask.

client.getMACAddress(): Promise<string>

Requests and resolves to the device's MAC address.

client.getGateway(): Promise<string>

Requests and resolves to the IP address of the standard network gateway used by the device.

client.getDNS(): Promise<string>

Requests and resolves to the IP address of the DNS server used by the device.

client.getDHCPStatus(): Promise<boolean>

Resolves to true if the device's network is configured via DHCP, false otherwise.

client.getTime(): Promise<Temporal.PlainDateTime>

Requests and resolves to the current local date and time of the device. The time has to be interpreted in the time zone returned by client.getTimeZone().

client.getUTCTime(): Promise<Temporal.ZonedDateTime>

Requests and resolves to the current UTC date and time of the device.

client.getTimeZone(): Promise<string>

Requests and resolves to the time zone used by the device.

client.getSoftwareRelease(): Promise<string>

Requests and resolves to the device's software release.

Low-level requests

client.send(values: RscpValue<any>[]): Promise<RscpValue<any>[]>

Sends the provided values (an array of RscpValues) in a single frame and resolves to the response received (also an array of RscpValues).

RscpValue

abstract class RscpValue<ValueType> {
  tag: RscpTag;
  value: ValueType;
  constructor(tag: RscpTag, value: ValueType);
}

Subclasses of RscpValue combine an RSCP type, a tag, and a value. The type is encoded in the concrete subclass, which also determines ValueType, while the tag and value are available as properties with these names. Unless otherwise noted, all subclasses share the same constructor signature. The following subclasses are available:

The RscpInt64Value and RscpUInt64Value constructors accept a bigint or a number for value. The RscpTimestampValue constructor also accepts a Date or the number of milliseconds in the epoch as a number.

RscpTag

An enum of all (as of March 2016) RSCP tags (without the leading TAG_), e.g. RscpTag.RSCP_REQ_AUTHENTICATION. See the RSCP specification.

RscpError

An enum of the RSCP error codes that can occur in an RscpErrorValue: