The console

A web page for a DNP3 master: what an outstation holds, what it reports, and every frame that passes, in a browser. It is for watching a device at a bench and for showing the software working.

py1815-master console --demo --open

That starts three things in one process and opens the page: a simulated IEEE 1815.2 DER listening as an outstation, a master connected to it, and the console at http://127.0.0.1:8815/.

It reads unless told otherwise

Started as above, the console polls, reads named points, takes unsolicited responses and shows the traffic, and can change nothing. Add --allow-control and it can operate outputs, write the time, clear the restart indication, freeze counters, write a DER's settings and curves and enable its functions, and run the checks that write. The top of the page says which: Read only or Commanding on. See Commanding.

Starting it

The demonstration needs the profile's point tables, which this library may not carry. Fetch them once:

py1815-der tables fetch

To watch an outstation that is already running, name it:

py1815-master console --outstation lab=192.0.2.10:20000 \
    --integrity-interval 30 --event-interval 2

Every option below except the token options and --demo can also be set in a JSON file and loaded with --config. See Configuring the master.

Option	Does
--config FILE	Loads settings from a JSON file. Flags given on the command line override it
--demo	Starts a simulated IEEE 1815.2 DER and connects to it
--outstation NAME=HOST:PORT	Adds an outstation and connects to it. May be given more than once
--outstation-address, --master-address	The link addresses, for the outstations named. 1024 and 1 unless given
--read-retries N	Sends a read that times out again, up to this many times. Nothing else is ever sent again. 0 unless given
--tls-ca, --tls-certificate, --tls-key FILE	Connects to the outstations named over TLS: the authorities their certificates are checked against, and the master's own certificate and key. See Configuring the master
--tls-server-name NAME	The name an outstation's certificate is checked against, when it is not the host
--integrity-interval SECONDS	Repeats an integrity poll of each outstation named
--event-interval SECONDS	Repeats an event poll
--unsolicited CLASSES	Enables unsolicited reporting for these event classes after startup, as in 1,2,3
--manual	Sends only what is asked for: no startup sequence, no event poll, no confirmation
--reconnect SECONDS	Seconds between reconnection attempts after a lost connection. 5 by default, 0 for never
--output-interval SECONDS	Repeats a read of output status. As often as the integrity poll unless given; 0 for never
--profile	The outstations named are IEEE 1815.2 DER: name their points from the profile, and let the console show the profile's points they have not reported
--tables FILE	The profile tables, for --demo and --profile
--device-profile FILE	A DNP3 Device Profile document for the outstations named, which the DER tab compares what they serve with, and lays out to read and to print
--bind HOST:PORT	Where the console listens. 127.0.0.1:8815 unless given
--token TOKEN	Required of every request to the service. Needed to listen on anything but this machine. Read from PY1815_MASTER_TOKEN when not given
--new-token	With no token given, makes one for this run and prints the address that carries it
--no-token	Listens beyond this machine with no token, for a container whose port is published to this machine only
--connect-wait SECONDS	Keeps trying, for this long, to connect to an outstation that is not there yet at startup
--allow-control	Lets the console command an outstation. Without it the controls are greyed out and the service refuses every such operation
--open	Opens the console in a browser

Outstations can also be added from the page, under Add outstation.

Once an outstation is connected, the master runs its automatic tasks:

• On connect, it runs an integrity poll. A master set to use unsolicited reporting first asks the outstation to stop it.
• It polls for events when a response says some are waiting, and polls again at once, up to three times, while a poll's own response still says so.
• It reconnects when the connection is lost.
• With --allow-control, it also clears the restart indication and writes the time when the outstation asks.

The Overview tab shows which tasks are enabled, and the Log records each time one runs. Manual, on the form and on the command line, disables them all.

In Docker

From a checkout, with nothing installed but Docker:

docker compose up

and open http://localhost:8815/. Three things run:

Service	Does
tables	Fetches the profile's point tables from IEEE into a volume, the first time only. They may not be redistributed, so each machine gets its own copy
der	A simulated IEEE 1815.2 DER, listening as an outstation
master	The master, connected to der, serving its API and the console

The master's image can also be run by itself, against any outstation:

docker build --target master -t py1815-master .
docker run --rm -p 127.0.0.1:8815:8815 py1815-master \
    console --bind 0.0.0.0:8815 --new-token --outstation lab=192.0.2.10:20000

Inside a container the console listens on every interface, and publishing the port is what decides who can reach it. Listening that widely needs a token, so:

• --new-token makes one for the run and prints the address that carries it.
• PY1815_MASTER_TOKEN gives one that stays the same from run to run.
• --no-token does without, for a port published to this machine only, as compose.yaml publishes it. A request then still has to name this machine as its host.

For a profile's point names in the image, mount the volume the tables were fetched into at /data and add --profile. --connect-wait 60 keeps trying for a minute to connect to an outstation that starts after the master does.

What it shows

Outstations are listed on the left, each with a lamp for its connection. The one selected has a row of tabs. DER is among them when the outstation was given a profile.

Tab	Shows
Overview	Addresses, connection state, the scans being repeated, how the requests so far ended, how many points of each type have been reported, what the master does for the outstation unasked, and every internal indication of the last response as a lamp
Points	A table for each point type
Commands	Scans, reads, operating outputs, the time and the counters, unsolicited responses, any request by function code, and the result of each
Events	Events as they arrive, newest first, and whether each was polled or sent unasked
Traffic	Every frame, and the one selected read layer by layer; saved as a capture
Requests	Requests you saved, each sent once or repeated
DER	The outstation as an IEEE 1815.2 DER: its nameplate, what it is measuring, each function with its settings and an enable switch, the curve the curve block shows, what it serves against its Device Profile document, and that document laid out for reading and printing. Offered for an outstation with a profile
Evaluate	The checks an evaluation runs and the report of the last run, and the deviations: protocol rules the master breaks on purpose
Log	What the console asked for, and what came of it

Points

One table for each of binary inputs, binary outputs, counters, frozen counters, analog inputs and analog outputs.

Column	Holds
Index	The point's index
Name	Its name, when the outstation has a profile
Value	ON or OFF, a count, or an analog value as transmitted
Flags	The flag bits that are set, by name. no flags for a variation that carries none, and none set when not even ONLINE is
Outstation time	The time the outstation gave the value, when it gave one
Object	The group and variation that carried it
Reported by	A static object, or an event
Age	How long since it was last reported

The table holds still while it is read. Its columns keep their widths, a row whose point has not changed is not redrawn, and a value is marked only when it or its flags change, not when the same value is reported again.

• Filter narrows the table by index, name or flag.
• Changed in the last 10 s shows only the points whose value or flags changed lately.
• Show points not reported lists the points of the profile the outstation has not reported, set back and marked NOT REPORTED, beside the ones it has, and counts each type against the profile. A mandatory point among them is marked. It is offered when the outstation has a profile.

A point is not reported either because the outstation does not implement it or because nobody has read it. A master cannot tell which from silence.

Outputs

An integrity poll does not return what the outputs stand at. The IEEE 1815.2 profile leaves output status out of class 0, so it is read by its groups. The console reads it as often as the integrity poll for an outstation given one, and Output status on the Commands tab reads it once.

A point that is an enumeration is named without the values it can take, and has a small i beside its name. Point at it, or reach it with the keyboard, and the values are listed one to a line:

0: Curve is not defined
1: Not applicable / Unknown
2: Volt-Var
3: Frequency-Watt

Commands

Card	Does
Scan	An integrity poll, an event poll, one class, or output status. Repeat sets how often each is made unasked, and an empty field stops it
Read points	One point type, by a list of indices or all
Operate outputs	Commands one binary or analog output. See Commanding
Clock, restart and counters	Writes the time, clears the restart indication, freezes the counters, or freezes and clears them
Unsolicited responses	Asks the outstation to report the classes ticked without being polled, or to stop
Request by function code	Any request: a function, and the object headers after it in hexadecimal

Each shows its result: the request, how it ended, how many fragments and objects came back, the indications, how long it took, and the objects. An outstation that does not answer is shown as a timeout, and one that refuses shows the indication it refused with.

Commanding

With --allow-control, Operate outputs commands one output:

Field	Is
Output	A binary output or an analog output
Index	The point
Operation	For a binary output: latch on, latch off, pulse on, pulse off, trip or close
Value	For an analog output: the number to send
Sent as	The variation: a 16- or 32-bit integer, or a float. Left alone, a whole number goes as an integer and anything else as a float
Mode	Select and then operate, direct operate, or direct operate with no acknowledgment

An outstation that scales its points, as an IEEE 1815.2 DER does, reads an integer as the value transmitted and a float as the engineering value: 500 as an integer on a point in tenths of a percent is 50 percent.

The result says what came of it:

Outcome	Means
Accepted	The outstation accepted every control
Refused	It answered, and refused. The table gives its status for the control
Not operated	A select was not accepted, so no operate was sent
Not known	It did not say: the request takes no acknowledgment, or the response did not arrive. The output may have been operated

Nothing is sent twice. After a select, the operate is sent only if the outstation echoed the control back unchanged and accepted it, and a scan the console repeats cannot fall between the two.

An integrity poll does not return what an output stands at, so with Read the output's status back afterwards ticked the console reads that one output once the request has gone, and the Points table shows what it now is.

In the Points tab, each row of the binary and analog output tables has an Operate button that opens the form filled in for that output.

Without --allow-control the form and the buttons are greyed out, and the service behind the page refuses the operations whoever asks.

Staying current

The console keeps the last 600 frames, 1,000 events and 300 log lines. If it falls behind the service, for example in a laptop that slept, or loses the connection to it, it reloads the selected outstation and says so in the Log tab. See Running for days.

DER

For an outstation given a profile (--profile, or console --demo), the DER tab shows it in the profile's terms, every value in engineering units with its units and quality. Opening the tab reads what it shows, and Read again reads it afresh. Each of those is a read: nothing is written until you ask.

Card	Shows
Nameplate	The points the profile lists as the nameplate: ratings, voltage limits, storage capacity
Monitoring	What the DER is measuring and reporting: available power, state of charge, the system meter
Functions	Each function the outstation says it supports, with a switch that enables or disables it and says whether it is, and Settings to read its settings and write one. The functions it does not support are named underneath
Curve	The curve the curve block shows, as a plot and a table of its points, with its type, its units and whether a function follows it
Device Profile comparison	What the outstation serves against what a Device Profile document declares
Device Profile document	A Device Profile document laid out for reading and printing: the outstation's own, or a file from your machine

A value marked OFFLINE was sent without the ONLINE flag. IEEE 1815.2 has a disabled function's inputs sent that way: the value is there and not in effect. Enabling the function brings them ONLINE.

Settings reads the function's points and offers a form: choose a setting, give a value in its units, and Write. The value is scaled by the point's multiplier on its way, a value outside the point's range is refused before anything is sent, and Read back and compare reads the input that mirrors the setting afterwards and says whether it matches. The result says Accepted, Refused or Not known, as for an operate, and nothing is sent twice.

The curve block shows one curve at a time. Show with a curve number selects another, which writes the selector, so it is a command. The plot and the table give the points as they travel: the units the curve declares say how they scale.

Compare with its Device Profile document is offered when the outstation was given one with --device-profile, and Compare with a Device Profile document takes a file from your machine. The result counts the points declared, served, declared and absent, served and undeclared, and in or out of class 0 against the declaration, and lists each one that differs. A point's event class and deadband cannot be asked of an outstation, so they are listed as the document declares them. console --demo gives the simulated DER the document it publishes.

A Device Profile is XML, which is not something to read. The Device Profile document card lays one out as a document:

• Show lays out the document the outstation was given with --device-profile. For an outstation given none, the card says so.
• or lay out another Device Profile XML file takes a file from your machine: any vendor's, written for any edition of the schema. The file is read as UTF-8. One that is not XML, or is not a Device Profile, is refused and the card says why.
• Print prints the document alone, without the rest of the console. Choose Save as PDF in the browser's print dialog to keep it as a file. A table's headings are repeated on each page, and a row is not split between two pages.

The document opens with its name, what its header states and the device's vendor, name and versions. Its parts follow in the document's own order:

Part	Is laid out as
The configuration	A table for each group of settings, with a row for each setting: what it is, its capabilities, its current value, and the methods by which it is configured where the document gives them
The database	The same, for each point type
The implementation table	A row for each object group and variation, with the function codes and qualifier codes of the requests it accepts and the responses it sends
The point lists	A table for each point type, with a row for each point and a column for each property the points carry

The layout is this library's own, and is not the one the DNP Users Group's stylesheet produces. A heading or a label is the element's own name made readable, as in "Max received fragment size", and is not the wording of the Users Group's template. Nothing is added: a value the document does not state is an empty cell, and anything the layout does not recognize is still shown, by its label and its text. To see a document in the Users Group's layout, open it with their stylesheet, as Serving a DER describes.

Laying a document out sends nothing to the outstation. py1815-der profile --from FILE --html FILE writes the same document as a page, with no console.

Without --allow-control the switches, the settings form and the curve block's Show are greyed out, and the service refuses those operations whoever asks. The Device Profile document card is not: laying a document out commands nothing.

Traffic

Each frame with its time, its direction and one line saying what it is:

→ READ seq 4: class 1, class 2, class 3
← RESPONSE seq 4 CON [NEED_TIME, DEVICE_RESTART]: g32v1 x7
→ CONFIRM seq 4

Select one and it is read beside its octets: the data link, the transport header, and the application fragment on the frame that completed one. Point at a layer and its octets are picked out; checksums are left unshaded. The view can be narrowed to one direction or to frames that carry an application fragment, paused, and cleared.

Save capture saves every frame the master has kept for the outstation as a pcap file, named for the outstation and the time, for Wireshark or any other tool that reads one. It saves both directions whatever the view is narrowed to, and nothing that was cleared. To keep everything from the start of a run instead, start the console with --capture FILE; see Captures.

A frame the master sent that is not a valid frame, which only a deviation produces, is listed as not a valid frame with what is wrong with it. Its data link layer gives the header fields as they were written and a Problem line. A field the octets are too short to hold is left out.

Requests

A list of requests you saved, each with a name, a function code by name, and the object headers after it in hexadecimal. A browser that has saved none starts with a few reads: an integrity poll, an event poll, class 0 and every binary input.

Control	Does
Send	Sends the request once, and shows its result as the Commands tab shows one
Repeat	Sends it now and then again every so many seconds, 0.2 at the least, until Stop
Edit	Puts the request in the form under the list, to change and Save
Remove	Deletes it from the list
Add	Saves the request typed into the form

The page checks nothing you type. The service reads the function code and the octets and says what is wrong with them, and the result shows what it said. A function code that changes the outstation is refused without --allow-control, as it is on the Commands tab: READ, ENABLE_UNSOLICITED, DISABLE_UNSOLICITED and DELAY_MEASURE are always sent.

The list is kept in the browser, under the address the console was opened at. It is there the next time the page is opened, and another browser or another console has its own. The page keeps up to 100 requests.

A repeated request is sent by the page on its own timer, and not by the master. It stops when the page is closed or another outstation is selected, and when a send is refused, fails or is not answered, which the list says beside the request. To have the master repeat a scan with no page open, use Repeat on the Commands tab.

Evaluate

The checks of Evaluating an outstation, run from the page, and the deviations of Misbehaving on purpose as switches.

Checks lists every check by set, in the order they run. A check marked writes writes to the outstation, and one marked deviates has the master break a protocol rule on purpose. Tick the checks to run. The box beside a set's name chooses the whole set, and All and None choose every check that may be chosen, or none. Every check that may be chosen is chosen to begin with. A check that is chosen is one that will be run, with one exception named below.

Run runs the chosen checks against the selected outstation. Each row is filled in as its check ends, with its verdict, the reason for it and what the check noted. A function check is listed by the output that enables its function, and once it has run its row names the function and says whether the outstation supports it. When the last has ended, the report counts the verdicts: passed, FAILED, not applicable and not run, as Verdicts defines them. A check that sent anything gives its requests, how long it took and its frames. Choosing the frames opens the Traffic tab narrowed to them, and Show all frames there widens it again. The master keeps a limited number of frames, and when it no longer keeps all of a check's the row says so and offers no link. Save report saves the report as a JSON file, the one py1815-master evaluate --report writes.

Two things decide which checks are run:

• A check that writes is run only when the console was started with --allow-control, and is otherwise reported as not run. The tab says which above the list. With it, the checks change the outstation's settings, curves and switches: see What a run leaves behind.
• A check that deviates cannot be chosen until Allow these checks on the deviation set's own row is switched on. Switching it on chooses them, and switching it off clears them. With it on, the master sends the outstation frames it has to discard and withholds confirmations it asked for, so use it on a device on a bench.

One evaluation runs against an outstation at a time, and a second is refused while it does. A run takes as long as its checks do, and goes on when another tab or another outstation is selected. The checks need the outstation's profile: for an outstation given none, the tab says so and offers no Run.

Deviations has a switch for each deviation, with what it makes the master do. A deviation that is on changes what the master sends that outstation, the scans it repeats included, until it is turned off. So the tab names the ones that are on, Deviations on stays beside the outstation's name on every tab, and Turn all off clears them. The switches show what the service reports, so a deviation a script turned on is shown as well. A check that deviates turns its own deviation on and off, and the switches cannot be changed while an evaluation runs.

Who can reach it

The console can read an outstation and, started with --allow-control, command one, so who can reach it matters.

• It listens on this machine only. To reach it from another, give it a token:

py1815-master console --bind 0.0.0.0:8815 --token "$(openssl rand -hex 16)"

It prints an address that carries the token, and refuses any request to the service without it. The page's own files need none: they are the same for everyone and say nothing about any outstation. It speaks plain HTTP, so put it behind something that speaks TLS if the network between is not yours.

• It takes a request only from its own page. A browser will carry a request from any site to a port on your machine, so a request whose Origin is another site, or that names a host this machine is not, is refused.

• It loads nothing from the network: no font, script or style. It works on a lab network that reaches nothing, and tells nobody that it is running.

What is behind it

The page holds no logic. It asks a service for things and shows what comes back, and anything it does a script can do with the same requests. See The master's API.