ser2netweb 3.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ser2netweb/__init__.py +20 -0
- ser2netweb/__main__.py +6 -0
- ser2netweb/accounts.py +503 -0
- ser2netweb/cli.py +489 -0
- ser2netweb/clock.py +128 -0
- ser2netweb/config.py +4491 -0
- ser2netweb/console.py +181 -0
- ser2netweb/datalock.py +181 -0
- ser2netweb/engine/__init__.py +0 -0
- ser2netweb/engine/access.py +173 -0
- ser2netweb/engine/bindhint.py +115 -0
- ser2netweb/engine/bridge.py +1928 -0
- ser2netweb/engine/cluster.py +1140 -0
- ser2netweb/engine/modbus.py +530 -0
- ser2netweb/engine/modbus_gateway.py +1465 -0
- ser2netweb/engine/mqtt_pub.py +632 -0
- ser2netweb/engine/netguard.py +805 -0
- ser2netweb/engine/netinfo.py +199 -0
- ser2netweb/engine/portdiag.py +414 -0
- ser2netweb/engine/portlist.py +471 -0
- ser2netweb/engine/protocols/__init__.py +28 -0
- ser2netweb/engine/protocols/base.py +117 -0
- ser2netweb/engine/protocols/raw.py +12 -0
- ser2netweb/engine/protocols/rfc2217.py +586 -0
- ser2netweb/engine/protocols/telnet.py +172 -0
- ser2netweb/engine/serial_compat.py +598 -0
- ser2netweb/engine/serial_io.py +210 -0
- ser2netweb/engine/serial_link.py +414 -0
- ser2netweb/engine/sockopts.py +103 -0
- ser2netweb/engine/sparkplug.py +538 -0
- ser2netweb/engine/sparkplug_node.py +550 -0
- ser2netweb/engine/supervisor.py +533 -0
- ser2netweb/engine/tls.py +232 -0
- ser2netweb/envvars.py +57 -0
- ser2netweb/explain.py +117 -0
- ser2netweb/healthcheck.py +78 -0
- ser2netweb/i18n.py +110 -0
- ser2netweb/importer.py +550 -0
- ser2netweb/layout.py +118 -0
- ser2netweb/licences.py +86 -0
- ser2netweb/locale/tr.json +1569 -0
- ser2netweb/logsetup.py +253 -0
- ser2netweb/logtext.py +23 -0
- ser2netweb/notify.py +761 -0
- ser2netweb/optional.py +76 -0
- ser2netweb/reload.py +295 -0
- ser2netweb/runtime.py +762 -0
- ser2netweb/sdnotify.py +85 -0
- ser2netweb/ser2net_import.py +2001 -0
- ser2netweb/signins.py +98 -0
- ser2netweb/standalone.py +154 -0
- ser2netweb/state.py +1457 -0
- ser2netweb/storage.py +130 -0
- ser2netweb/textfold.py +51 -0
- ser2netweb/tlsreload.py +37 -0
- ser2netweb/watchdog.py +201 -0
- ser2netweb/web/__init__.py +0 -0
- ser2netweb/web/api.py +793 -0
- ser2netweb/web/auth.py +699 -0
- ser2netweb/web/certinfo.py +144 -0
- ser2netweb/web/httpguard.py +413 -0
- ser2netweb/web/ldap_auth.py +556 -0
- ser2netweb/web/oidc_auth.py +330 -0
- ser2netweb/web/proxy.py +398 -0
- ser2netweb/web/routes/__init__.py +78 -0
- ser2netweb/web/routes/cluster.py +669 -0
- ser2netweb/web/routes/common.py +359 -0
- ser2netweb/web/routes/console.py +451 -0
- ser2netweb/web/routes/forms.py +853 -0
- ser2netweb/web/routes/login.py +573 -0
- ser2netweb/web/routes/mappings.py +470 -0
- ser2netweb/web/routes/ops.py +374 -0
- ser2netweb/web/routes/settings.py +2135 -0
- ser2netweb/web/routes/system.py +308 -0
- ser2netweb/web/routes/totp.py +282 -0
- ser2netweb/web/selfsigned.py +129 -0
- ser2netweb/web/server.py +483 -0
- ser2netweb/web/static/app.css +327 -0
- ser2netweb/web/static/app.js +1102 -0
- ser2netweb/web/static/htmx.min.js +1 -0
- ser2netweb/web/static/points.js +218 -0
- ser2netweb/web/static/theme.js +7 -0
- ser2netweb/web/static/xterm-addon-fit.js +2 -0
- ser2netweb/web/static/xterm.css +218 -0
- ser2netweb/web/static/xterm.js +2 -0
- ser2netweb/web/templates/_cluster_body.html +109 -0
- ser2netweb/web/templates/_console.html +21 -0
- ser2netweb/web/templates/_footer.html +13 -0
- ser2netweb/web/templates/_login_notice.html +8 -0
- ser2netweb/web/templates/_macros.html +21 -0
- ser2netweb/web/templates/_mapping_form.html +477 -0
- ser2netweb/web/templates/_mapping_log.html +28 -0
- ser2netweb/web/templates/_mapping_traces.html +44 -0
- ser2netweb/web/templates/_mappings_body.html +149 -0
- ser2netweb/web/templates/_modbus_read.html +18 -0
- ser2netweb/web/templates/_ports_table.html +37 -0
- ser2netweb/web/templates/_serial_port_select.html +48 -0
- ser2netweb/web/templates/_shell.html +41 -0
- ser2netweb/web/templates/audit.html +55 -0
- ser2netweb/web/templates/base.html +77 -0
- ser2netweb/web/templates/dashboard.html +72 -0
- ser2netweb/web/templates/licenses.html +18 -0
- ser2netweb/web/templates/login.html +32 -0
- ser2netweb/web/templates/login_totp.html +23 -0
- ser2netweb/web/templates/settings.html +830 -0
- ser2netweb/web/templates/setup.html +43 -0
- ser2netweb/web/templates/totp.html +41 -0
- ser2netweb/web/totp.py +94 -0
- ser2netweb/winservice.py +1793 -0
- ser2netweb-3.0.0.dist-info/METADATA +120 -0
- ser2netweb-3.0.0.dist-info/RECORD +121 -0
- ser2netweb-3.0.0.dist-info/WHEEL +5 -0
- ser2netweb-3.0.0.dist-info/entry_points.txt +2 -0
- ser2netweb-3.0.0.dist-info/licenses/COMMERCIAL_LICENSE.md +94 -0
- ser2netweb-3.0.0.dist-info/licenses/LICENSE +662 -0
- ser2netweb-3.0.0.dist-info/licenses/NOTICE +20 -0
- ser2netweb-3.0.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +105 -0
- ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/htmx.org.txt +13 -0
- ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm-addon-fit.txt +19 -0
- ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm.txt +21 -0
- ser2netweb-3.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
"""Low-level async serial open/resolve helpers built on pyserial-asyncio-fast.
|
|
2
|
+
|
|
3
|
+
Kept separate from the bridge so the device-resolution and pyserial-config
|
|
4
|
+
mapping live in one place. ``resolve_device`` re-resolves a stable hardware
|
|
5
|
+
identity (VID/PID/serial) to a current device path so COMx / ttyUSB* renumbering
|
|
6
|
+
doesn't break a mapping across reconnects. The port class, the transport and the stream
|
|
7
|
+
on top of them are serial_compat's (which also holds ser2netweb's fixes for pyserial and
|
|
8
|
+
pyserial-asyncio-fast).
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import asyncio
|
|
13
|
+
import contextlib
|
|
14
|
+
import errno
|
|
15
|
+
import sys
|
|
16
|
+
import weakref
|
|
17
|
+
from typing import Any, Optional
|
|
18
|
+
|
|
19
|
+
from ..config import SerialSettings, identity_text, url_port, usb_identity
|
|
20
|
+
from . import portdiag, portlist
|
|
21
|
+
|
|
22
|
+
# StreamReader high-water for the serial side. The default (64 KB) makes the reader
|
|
23
|
+
# pause/resume frequently under load; we read promptly in the bridge and apply our
|
|
24
|
+
# own per-client backpressure, so a larger buffer keeps the serial read flowing.
|
|
25
|
+
SERIAL_STREAM_LIMIT = 1024 * 1024
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _match_listed(p: dict[str, Any], want: dict[str, Any]) -> bool:
|
|
29
|
+
"""Whether port ``p`` of portlist's list (IDs as hex strings) has the USB identity
|
|
30
|
+
``want`` (config.usb_identity: only known keys). A serial number is compared in any
|
|
31
|
+
letter case (Linux and Windows may read one adapter's apart)."""
|
|
32
|
+
for key in ("vid", "pid"):
|
|
33
|
+
if want.get(key) and (p.get(key) or "") != str(want[key]).lower():
|
|
34
|
+
return False
|
|
35
|
+
if want.get("serial_number") and (
|
|
36
|
+
str(p.get("serial_number") or "").casefold() != str(want["serial_number"]).casefold()):
|
|
37
|
+
return False
|
|
38
|
+
if want.get("location") and p.get("location") != want["location"]:
|
|
39
|
+
return False
|
|
40
|
+
return True
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class ForeignDevice(OSError):
|
|
44
|
+
"""The port a mapping is set to is another USB device now, and the one it is bound to is
|
|
45
|
+
not there: it is not opened (errno ENODEV: the state is device-missing)."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _enumerate() -> list[dict[str, Any]]:
|
|
49
|
+
"""The serial ports with their USB identities, enumerated now (blocking)."""
|
|
50
|
+
from serial.tools import list_ports
|
|
51
|
+
|
|
52
|
+
return [portlist._normalize(p) for p in list_ports.comports()]
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def resolve(settings: SerialSettings,
|
|
56
|
+
ports: Optional[list[dict[str, Any]]] = None) -> tuple[str, list[str]]:
|
|
57
|
+
"""The device to open for ``settings``, and the ports that have the USB identity it is
|
|
58
|
+
bound to (sorted; [] for a port opened by its name). ``ports`` is portlist's list; without
|
|
59
|
+
it the ports are enumerated (blocking).
|
|
60
|
+
|
|
61
|
+
Of several ports with that identity (identical adapters without their own serial number,
|
|
62
|
+
the channels of an FT4232H), the configured port is opened when it is one of them (also
|
|
63
|
+
through a /dev/serial/by-id or by-path link), else the first one no other mapping of this
|
|
64
|
+
process has open. When no port has it and the configured port is now another USB device,
|
|
65
|
+
ForeignDevice is raised instead of opening that one; a configured port that is not there
|
|
66
|
+
or has no USB identity is opened by its name (and fails as missing when it is not
|
|
67
|
+
there)."""
|
|
68
|
+
want = usb_identity(settings.match)
|
|
69
|
+
if not want:
|
|
70
|
+
return settings.port, []
|
|
71
|
+
listed = _enumerate() if ports is None else ports
|
|
72
|
+
matches = sorted(p["device"] for p in listed if p.get("device") and _match_listed(p, want))
|
|
73
|
+
if matches:
|
|
74
|
+
mine = next((d for d in matches if portlist.same_port(settings.port, d)), None)
|
|
75
|
+
if mine is None:
|
|
76
|
+
free = [d for d in matches if not portdiag.holder(d)]
|
|
77
|
+
mine = (free or matches)[0]
|
|
78
|
+
return mine, matches
|
|
79
|
+
here = portlist.find(listed, settings.port, resolve=True)
|
|
80
|
+
if here is not None and here.get("vid"):
|
|
81
|
+
raise ForeignDevice(
|
|
82
|
+
errno.ENODEV,
|
|
83
|
+
f"could not open port {settings.port}: it is another USB device now "
|
|
84
|
+
f"({identity_text(here)}), not the one this mapping is bound to "
|
|
85
|
+
f"({identity_text(want)}), so it is not opened; plug that one in, or bind the "
|
|
86
|
+
"mapping to this one in its form")
|
|
87
|
+
return settings.port, []
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def resolve_device(settings: SerialSettings,
|
|
91
|
+
ports: Optional[list[dict[str, Any]]] = None) -> str:
|
|
92
|
+
"""The device path to open for ``settings`` (resolve)."""
|
|
93
|
+
return resolve(settings, ports)[0]
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
async def _resolve(settings: SerialSettings) -> tuple[str, list[str]]:
|
|
97
|
+
"""resolve without blocking the event loop: from the port list the PortWatcher keeps
|
|
98
|
+
(fresh within a poll or two), else enumerated in a thread."""
|
|
99
|
+
if not settings.identity:
|
|
100
|
+
return settings.port, []
|
|
101
|
+
ports = portlist.recent()
|
|
102
|
+
if ports is not None:
|
|
103
|
+
return resolve(settings, ports)
|
|
104
|
+
return await asyncio.to_thread(resolve, settings)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def refuse_url(device: str) -> None:
|
|
108
|
+
"""Raise ValueError for a port written as a URL (socket://, rfc2217://, spy://, loop://
|
|
109
|
+
...): pyserial would hand it to a URL handler, which opens a network connection or a
|
|
110
|
+
file instead of a serial device. Edits refuse such ports (MappingConfig.validate_input);
|
|
111
|
+
this keeps a stored one (hand-edited, restored, older config) from ever being opened."""
|
|
112
|
+
if url_port(device):
|
|
113
|
+
raise ValueError(f"serial port {device!r} is a URL, not a serial device; "
|
|
114
|
+
"URL ports are not opened")
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def port_settings(settings: SerialSettings) -> dict[str, Any]:
|
|
118
|
+
"""The pyserial settings a mapping's port is opened with: baud rate, data bits, parity,
|
|
119
|
+
stop bits and flow control (in the order pyserial applies them)."""
|
|
120
|
+
return dict(
|
|
121
|
+
baudrate=settings.baudrate,
|
|
122
|
+
bytesize=settings.bytesize,
|
|
123
|
+
parity=settings.parity,
|
|
124
|
+
stopbits=settings.stopbits,
|
|
125
|
+
xonxoff=(settings.flowcontrol == "xonxoff"),
|
|
126
|
+
rtscts=(settings.flowcontrol == "rtscts"),
|
|
127
|
+
dsrdtr=(settings.flowcontrol == "dsrdtr"),
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
_LINE_STATES = {"on": True, "off": False} # rts_on_open / dtr_on_open; "keep": pyserial's
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
async def open_serial(settings: SerialSettings):
|
|
135
|
+
"""Open the serial port asynchronously.
|
|
136
|
+
|
|
137
|
+
Returns (reader, writer, serial_instance, device_path). Raises
|
|
138
|
+
serial.SerialException / OSError if the device can't be opened, ValueError for a
|
|
139
|
+
URL port (refuse_url).
|
|
140
|
+
|
|
141
|
+
RTS / DTR set to on or off are in that state from the moment the port opens, and are
|
|
142
|
+
set again once it is open (pyserial skips them quietly when the port has no modem
|
|
143
|
+
lines, a PTY for one). A setting the port did not take (that, or RS-485 mode) does not
|
|
144
|
+
fail the open: open_notes(serial_instance) has it (portdiag.Note) for the caller to
|
|
145
|
+
report, with what else may use the port (portdiag.port_notes: the kernel console, a
|
|
146
|
+
login prompt). A refused RS-485 mode is also taken back, as pyserial keeps it and would
|
|
147
|
+
fail every later change of the port's settings with it (an RFC 2217 client's baud
|
|
148
|
+
rate)."""
|
|
149
|
+
device, matches = await _resolve(settings)
|
|
150
|
+
refuse_url(device) # the one place every serial port is opened
|
|
151
|
+
found: list[portdiag.Note] = await portdiag.about_port(device)
|
|
152
|
+
if len(matches) > 1 and not portlist.same_port(settings.port, device):
|
|
153
|
+
# a guess: identical adapters (no serial number of their own) can't be told apart
|
|
154
|
+
found.append(portdiag.Note("identity_shared", (
|
|
155
|
+
identity_text(settings.match), len(matches), device)))
|
|
156
|
+
kwargs: dict[str, Any] = port_settings(settings)
|
|
157
|
+
# `exclusive` is POSIX-only in pyserial; Windows ports are exclusive anyway.
|
|
158
|
+
if sys.platform != "win32":
|
|
159
|
+
kwargs["exclusive"] = settings.exclusive
|
|
160
|
+
|
|
161
|
+
import serial.rs485
|
|
162
|
+
|
|
163
|
+
from . import serial_compat
|
|
164
|
+
|
|
165
|
+
rts, dtr = _LINE_STATES.get(settings.rts_on_open), _LINE_STATES.get(settings.dtr_on_open)
|
|
166
|
+
adv = settings.advanced
|
|
167
|
+
keep_out = {"tiocexcl": bool(adv.tiocexcl),
|
|
168
|
+
"respect_uucp_locks": bool(adv.respect_uucp_locks)}
|
|
169
|
+
reader, writer = await serial_compat.open_stream(device, SERIAL_STREAM_LIMIT, rts=rts,
|
|
170
|
+
dtr=dtr, keep_out=keep_out, **kwargs)
|
|
171
|
+
transport: Any = writer.transport # serial_compat.Transport
|
|
172
|
+
ser = transport.serial
|
|
173
|
+
|
|
174
|
+
for line, want in (("RTS", rts), ("DTR", dtr)):
|
|
175
|
+
if want is not None:
|
|
176
|
+
try:
|
|
177
|
+
setattr(ser, line.lower(), want)
|
|
178
|
+
except Exception as e: # ENOTTY / EINVAL: no modem lines; Windows: refused
|
|
179
|
+
found.append(portdiag.Note("line", (line, want, portdiag.reason(e))))
|
|
180
|
+
|
|
181
|
+
# RS-485 (hardware/OS dependent): never fatal, so a port without it still opens
|
|
182
|
+
if adv.rs485_enabled:
|
|
183
|
+
try:
|
|
184
|
+
ser.rs485_mode = serial.rs485.RS485Settings(
|
|
185
|
+
rts_level_for_tx=adv.rs485_rts_level_for_tx,
|
|
186
|
+
rts_level_for_rx=not adv.rs485_rts_level_for_tx,
|
|
187
|
+
delay_before_tx=(adv.rs485_delay_before_tx_ms / 1000.0) or None,
|
|
188
|
+
delay_before_rx=(adv.rs485_delay_after_tx_ms / 1000.0) or None,
|
|
189
|
+
)
|
|
190
|
+
except Exception as e: # Linux: ENOTTY on most USB adapters; Windows: delays
|
|
191
|
+
with contextlib.suppress(Exception):
|
|
192
|
+
ser.rs485_mode = None
|
|
193
|
+
found.append(portdiag.Note("rs485", (portdiag.reason(e),)))
|
|
194
|
+
|
|
195
|
+
if found:
|
|
196
|
+
_NOTES[ser] = found
|
|
197
|
+
return reader, writer, ser, device
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
# what open_serial found about a port it opened (a setting it did not take, ...), by port
|
|
201
|
+
_NOTES: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary()
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def open_notes(ser: Any) -> list[portdiag.Note]:
|
|
205
|
+
"""What open_serial found about the open port ``ser`` (portdiag.Note), [] if nothing
|
|
206
|
+
(or for a port it did not open)."""
|
|
207
|
+
try:
|
|
208
|
+
return list(_NOTES.get(ser, ()))
|
|
209
|
+
except TypeError: # (a stand-in that can't be weakly referenced)
|
|
210
|
+
return []
|
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
"""A mapping's serial port, kept open for as long as the mapping runs.
|
|
2
|
+
|
|
3
|
+
Shared by the transparent bridge (bridge.MappingRunner) and the Modbus gateway
|
|
4
|
+
(modbus_gateway.ModbusGatewayRunner), so both open, lose and reopen a port the same way.
|
|
5
|
+
``SerialLink.run(session)`` opens the port (serial_io.open_serial re-resolves a stable USB
|
|
6
|
+
identity on every open), runs ``session(reader, writer)`` while it is open and, when the
|
|
7
|
+
port can't be opened or goes away, records why in the runner's status and reopens it after
|
|
8
|
+
a capped backoff, until the mapping stops (the runner cancels the task).
|
|
9
|
+
|
|
10
|
+
The link's state, for the runner and anything built on it:
|
|
11
|
+
- ``is_open`` / ``ready``: the port is open right now (``ready`` is the Event to wait on);
|
|
12
|
+
- ``down``: it could not be opened or went away, and is not open again yet; False until
|
|
13
|
+
the first attempt is over (at start-up the port may simply not be open *yet*);
|
|
14
|
+
- ``reader`` / ``writer`` / ``serial`` / ``device``: the open port (None / "" otherwise);
|
|
15
|
+
``on_change`` (optional) is told each time ``serial`` changes: the pyserial object of
|
|
16
|
+
a port just opened, None when it is closed (what drives the port itself, an RFC 2217
|
|
17
|
+
session, follows it);
|
|
18
|
+
- ``status.state``: ``running`` while it is open, ``device-missing`` / ``reconnecting``
|
|
19
|
+
while it is not (what the dashboard, /metrics and the notifications report):
|
|
20
|
+
``device-missing`` when the last open found no such device (portdiag.missing),
|
|
21
|
+
``reconnecting`` otherwise (the port went away, or can't be opened for another reason);
|
|
22
|
+
``status.open_failures`` / ``status.device_lost`` count failed opens and losses of the
|
|
23
|
+
open port (``reconnects`` both, as before); ``status.hangups`` the losses after which
|
|
24
|
+
the first try opened the same device again (POSIX: a hang-up, by a login prompt on
|
|
25
|
+
the port for one, not an unplug);
|
|
26
|
+
``status.hint``: what the error of a failed open means (portdiag.explain);
|
|
27
|
+
``status.warnings``: a setting the open port did not take (serial_io.open_notes),
|
|
28
|
+
logged when it differs from the last open's.
|
|
29
|
+
While the port can't be opened, the log says so once, again only when the error changes or
|
|
30
|
+
every FAILING_SUMMARY_S (FailureLog), and how long it was down once it opens again.
|
|
31
|
+
"""
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
import asyncio
|
|
35
|
+
import contextlib
|
|
36
|
+
import os
|
|
37
|
+
import sys
|
|
38
|
+
import time
|
|
39
|
+
from typing import TYPE_CHECKING, Any, Awaitable, Callable, Iterable, Optional
|
|
40
|
+
|
|
41
|
+
from . import portdiag, portlist, serial_io
|
|
42
|
+
|
|
43
|
+
if TYPE_CHECKING:
|
|
44
|
+
from ..config import SerialSettings
|
|
45
|
+
from .bridge import RunnerStatus
|
|
46
|
+
|
|
47
|
+
# a session runs while the port is open and returns or raises once it is gone
|
|
48
|
+
Session = Callable[[asyncio.StreamReader, asyncio.StreamWriter], Awaitable[None]]
|
|
49
|
+
|
|
50
|
+
# closing a port: what is still waiting to be written to the device gets this long to go
|
|
51
|
+
# out (then it is dropped), and so does the close itself after that
|
|
52
|
+
SERIAL_CLOSE_TIMEOUT_S = 2.0
|
|
53
|
+
_SENT_POLL_S = 0.05 # how often a close looks whether the port has sent everything
|
|
54
|
+
# while something keeps failing in the same way (a port that can't be opened, a connect-out)
|
|
55
|
+
# the log says so again this often, instead of at every attempt (FailureLog)
|
|
56
|
+
FAILING_SUMMARY_S = 900.0
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def fmt_duration(secs: float) -> str:
|
|
60
|
+
secs = max(0, int(secs))
|
|
61
|
+
h, rem = divmod(secs, 3600)
|
|
62
|
+
m, s = divmod(rem, 60)
|
|
63
|
+
if h:
|
|
64
|
+
return f"{h}h {m:02d}m"
|
|
65
|
+
if m:
|
|
66
|
+
return f"{m}m {s:02d}s"
|
|
67
|
+
return f"{s}s"
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class FailureLog:
|
|
71
|
+
"""The log lines of something tried again and again until it works (a serial port that
|
|
72
|
+
can't be opened, a connect-out): the first failure and each change of the error, then
|
|
73
|
+
the same error only every ``every`` seconds, with how many attempts failed since when;
|
|
74
|
+
recovered() ends it, with how long it lasted for the line that says it works again.
|
|
75
|
+
(A missing USB adapter used to write the same line at every retry, about 8,500 a day,
|
|
76
|
+
which pushed what happened first out of the log viewer within hours.)"""
|
|
77
|
+
|
|
78
|
+
def __init__(self, log: Callable[[str], None], prefix: str,
|
|
79
|
+
every: float = FAILING_SUMMARY_S) -> None:
|
|
80
|
+
self._log = log
|
|
81
|
+
self._prefix = prefix
|
|
82
|
+
self._every = every
|
|
83
|
+
self.error = "" # the last failure's error ("" while it works)
|
|
84
|
+
self.failures = 0 # failures since it last worked
|
|
85
|
+
self.since = 0.0 # time.time() of the first of them (the "since" it logs)
|
|
86
|
+
self._since_mono = 0.0 # the same by time.monotonic(): how long it was down
|
|
87
|
+
self._next = 0.0 # time.monotonic() of the next summary
|
|
88
|
+
|
|
89
|
+
def failed(self, error: str) -> bool:
|
|
90
|
+
"""Count a failure and log it as said above; True when it is the first one, or
|
|
91
|
+
the error changed."""
|
|
92
|
+
now = time.monotonic()
|
|
93
|
+
if not self.failures:
|
|
94
|
+
self.since, self._since_mono = time.time(), now
|
|
95
|
+
self.failures += 1
|
|
96
|
+
new = error != self.error
|
|
97
|
+
self.error = error
|
|
98
|
+
if new:
|
|
99
|
+
self._log(f"{self._prefix}: {error}")
|
|
100
|
+
elif now >= self._next:
|
|
101
|
+
since = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(self.since))
|
|
102
|
+
self._log(f"{self._prefix}: {error} (still failing: {self.failures} attempts "
|
|
103
|
+
f"since {since})")
|
|
104
|
+
else:
|
|
105
|
+
return False
|
|
106
|
+
self._next = now + self._every
|
|
107
|
+
return new
|
|
108
|
+
|
|
109
|
+
def recovered(self) -> str:
|
|
110
|
+
"""It works again: what to add to the line that says so (" (back after 5m 12s)"),
|
|
111
|
+
"" when nothing had failed."""
|
|
112
|
+
if not self.failures:
|
|
113
|
+
return ""
|
|
114
|
+
took = fmt_duration(time.monotonic() - self._since_mono) # (a clock step aside)
|
|
115
|
+
self.error, self.failures, self.since = "", 0, 0.0
|
|
116
|
+
return f" (back after {took})"
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class Backoff:
|
|
120
|
+
"""The pause between reconnect attempts: 0.5 s doubling up to ``cap`` (10 s), plus up
|
|
121
|
+
to 0.4 s of jitter derived from the attempt number (not an RNG). ``attempt`` counts the
|
|
122
|
+
attempts since the last success; reset() after one. wake() ends a pause under way (a
|
|
123
|
+
serial device just appeared: no need to wait up to 10 s for it)."""
|
|
124
|
+
|
|
125
|
+
def __init__(self, cap: float = 10.0) -> None:
|
|
126
|
+
self.cap = cap
|
|
127
|
+
self.attempt = 0
|
|
128
|
+
self._delay = 0.5
|
|
129
|
+
self._woken: Optional[asyncio.Event] = None # set by wake() while wait() sleeps
|
|
130
|
+
|
|
131
|
+
def reset(self) -> None:
|
|
132
|
+
self.attempt, self._delay = 0, 0.5
|
|
133
|
+
|
|
134
|
+
def pause(self) -> float:
|
|
135
|
+
"""The pause before the next attempt (what wait() sleeps), counting that attempt."""
|
|
136
|
+
self.attempt += 1
|
|
137
|
+
pause = min(self._delay, self.cap) + (self.attempt % 5) * 0.1
|
|
138
|
+
self._delay = min(self._delay * 2, self.cap)
|
|
139
|
+
return pause
|
|
140
|
+
|
|
141
|
+
async def wait(self, stop: asyncio.Event) -> bool:
|
|
142
|
+
"""Sleep before the next attempt (or until wake()); False when ``stop`` was set
|
|
143
|
+
meanwhile."""
|
|
144
|
+
pause = self.pause()
|
|
145
|
+
woken = self._woken = asyncio.Event()
|
|
146
|
+
waits = (asyncio.ensure_future(stop.wait()), asyncio.ensure_future(woken.wait()))
|
|
147
|
+
try:
|
|
148
|
+
await asyncio.wait(waits, timeout=pause, return_when=asyncio.FIRST_COMPLETED)
|
|
149
|
+
finally:
|
|
150
|
+
for w in waits:
|
|
151
|
+
w.cancel()
|
|
152
|
+
self._woken = None
|
|
153
|
+
return not stop.is_set()
|
|
154
|
+
|
|
155
|
+
def wake(self) -> None:
|
|
156
|
+
"""End the pause wait() is in, if any: try again now."""
|
|
157
|
+
if self._woken is not None:
|
|
158
|
+
self._woken.set()
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
class SerialLink:
|
|
162
|
+
def __init__(self, settings: SerialSettings, status: RunnerStatus, stop: asyncio.Event,
|
|
163
|
+
log: Callable[[str], None],
|
|
164
|
+
on_change: Optional[Callable[[Any], None]] = None, owner: str = "") -> None:
|
|
165
|
+
self.settings = settings
|
|
166
|
+
self.owner = owner # the mapping's name ("mapping X has this port open")
|
|
167
|
+
self.status = status
|
|
168
|
+
self._stop = stop
|
|
169
|
+
self._log = log
|
|
170
|
+
self._on_change = on_change
|
|
171
|
+
self.reader: Optional[asyncio.StreamReader] = None
|
|
172
|
+
self.writer: Optional[asyncio.StreamWriter] = None
|
|
173
|
+
self.serial: Any = None # the pyserial object (an RFC2217 session drives it)
|
|
174
|
+
self.device = ""
|
|
175
|
+
self.ready = asyncio.Event()
|
|
176
|
+
self.down = False
|
|
177
|
+
self._notes = NoteLog(log)
|
|
178
|
+
self._failures = FailureLog(log, "serial error")
|
|
179
|
+
self._backoff: Optional[Backoff] = None # run()'s, while it runs
|
|
180
|
+
# POSIX: the open port's device number, and that of a port that went away while
|
|
181
|
+
# no open has failed since (a hang-up, if the first try opens the same device)
|
|
182
|
+
self._rdev: Optional[int] = None
|
|
183
|
+
self._lost_rdev: Optional[int] = None
|
|
184
|
+
|
|
185
|
+
@property
|
|
186
|
+
def is_open(self) -> bool:
|
|
187
|
+
return self.ready.is_set()
|
|
188
|
+
|
|
189
|
+
async def run(self, session: Session) -> None:
|
|
190
|
+
"""Keep the port open until ``stop`` is set: open it, run ``session`` while it is
|
|
191
|
+
open, close it once the session ends, and try again after a backoff."""
|
|
192
|
+
backoff = self._backoff = Backoff()
|
|
193
|
+
self.down = False # the first attempt is under way
|
|
194
|
+
while not self._stop.is_set():
|
|
195
|
+
was_open = False
|
|
196
|
+
try:
|
|
197
|
+
reader, writer, ser, device = await serial_io.open_serial(self.settings)
|
|
198
|
+
was_open = True
|
|
199
|
+
self.attach(reader, writer, ser, device)
|
|
200
|
+
backoff.reset()
|
|
201
|
+
await session(reader, writer)
|
|
202
|
+
if not self._stop.is_set(): # (a session ends by raising why)
|
|
203
|
+
raise ConnectionError("serial EOF / device removed")
|
|
204
|
+
except asyncio.CancelledError:
|
|
205
|
+
raise
|
|
206
|
+
except Exception as e: # SerialException, OSError, the port went away
|
|
207
|
+
if not self._stop.is_set():
|
|
208
|
+
await self._failed(e, was_open)
|
|
209
|
+
finally:
|
|
210
|
+
await self.close()
|
|
211
|
+
if self._stop.is_set():
|
|
212
|
+
break
|
|
213
|
+
self.status.reconnects += 1
|
|
214
|
+
if not await backoff.wait(self._stop):
|
|
215
|
+
break
|
|
216
|
+
|
|
217
|
+
def wake(self) -> None:
|
|
218
|
+
"""Try to open the port now if run() is waiting to try again (a serial device was
|
|
219
|
+
plugged in, PortWatcher saw it)."""
|
|
220
|
+
if self._backoff is not None and not self.is_open:
|
|
221
|
+
self._backoff.wake()
|
|
222
|
+
|
|
223
|
+
async def _failed(self, e: Exception, was_open: bool) -> None:
|
|
224
|
+
"""The port could not be opened, or went away (``was_open``): say why in the status
|
|
225
|
+
and the log (FailureLog), and what that means."""
|
|
226
|
+
st = self.status
|
|
227
|
+
st.last_error = str(e)
|
|
228
|
+
if was_open:
|
|
229
|
+
st.device_lost += 1
|
|
230
|
+
st.state = "reconnecting"
|
|
231
|
+
self._lost_rdev = self._rdev # (no stat now: an unplug may still be under way)
|
|
232
|
+
else:
|
|
233
|
+
st.open_failures += 1
|
|
234
|
+
st.state = "device-missing" if portdiag.missing(e) else "reconnecting"
|
|
235
|
+
self._lost_rdev = None
|
|
236
|
+
self._failures.failed(str(e))
|
|
237
|
+
# (worked out at every failed open: the same error can come to mean something else,
|
|
238
|
+
# a user just added to the device's group needs a restart)
|
|
239
|
+
st.hint = None if was_open else await asyncio.to_thread(explain, e, self.settings)
|
|
240
|
+
|
|
241
|
+
def attach(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter,
|
|
242
|
+
serial: Any = None, device: str = "") -> None:
|
|
243
|
+
"""Mark an open port as the link's: what run() does after each open (a test can
|
|
244
|
+
use it to wire up a stand-in stream pair)."""
|
|
245
|
+
changed = serial is not self.serial
|
|
246
|
+
self.reader, self.writer, self.serial, self.device = reader, writer, serial, device
|
|
247
|
+
self._rdev = _rdev(serial)
|
|
248
|
+
if self._lost_rdev is not None and self._lost_rdev == self._rdev:
|
|
249
|
+
# the port went away and the very next try opened the same device: hung up
|
|
250
|
+
# (a login prompt's vhangup, another program), not unplugged
|
|
251
|
+
self.status.hangups += 1
|
|
252
|
+
self._log("serial port was hung up while open and could be reopened at once: "
|
|
253
|
+
"another program may be using it (a login prompt on it?)")
|
|
254
|
+
self._lost_rdev = None
|
|
255
|
+
notes = serial_io.open_notes(serial)
|
|
256
|
+
hangups = self.status.hangups
|
|
257
|
+
hung_up = (portdiag.Note("hangups", (hangups,)),) if hangups else ()
|
|
258
|
+
self.status.device = device
|
|
259
|
+
self.status.devices = (device,) if device else ()
|
|
260
|
+
self.status.last_error = ""
|
|
261
|
+
self.status.hint = None
|
|
262
|
+
self.status.warnings = tuple(notes) + hung_up
|
|
263
|
+
self.status.state = "running"
|
|
264
|
+
self.down = False
|
|
265
|
+
self.ready.set()
|
|
266
|
+
portdiag.opened(serial, self.owner, device)
|
|
267
|
+
self._log(f"serial open: {device} @ {self.settings.compact()}"
|
|
268
|
+
f"{self._failures.recovered()}")
|
|
269
|
+
self._notes(notes)
|
|
270
|
+
if changed:
|
|
271
|
+
self._changed(serial)
|
|
272
|
+
|
|
273
|
+
async def close(self) -> None:
|
|
274
|
+
"""Close the port if it is open; the link is down afterwards (also after an open
|
|
275
|
+
that failed: run() closes after every attempt)."""
|
|
276
|
+
self.down = True
|
|
277
|
+
self.ready.clear()
|
|
278
|
+
w, had_serial = self.writer, self.serial is not None
|
|
279
|
+
self.reader = self.writer = self.serial = None
|
|
280
|
+
self.device = ""
|
|
281
|
+
self.status.warnings = ()
|
|
282
|
+
if had_serial:
|
|
283
|
+
self._changed(None)
|
|
284
|
+
if w is not None:
|
|
285
|
+
await close_stream(w, self._log)
|
|
286
|
+
|
|
287
|
+
def _changed(self, serial: Any) -> None:
|
|
288
|
+
if self._on_change is not None:
|
|
289
|
+
try:
|
|
290
|
+
self._on_change(serial)
|
|
291
|
+
except Exception as e: # what follows the port must not break the link
|
|
292
|
+
self._log(f"serial port change not taken up: {type(e).__name__}: {e}")
|
|
293
|
+
|
|
294
|
+
async def hold_open(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
|
|
295
|
+
"""A session for a runner that reads the port only when it needs to (the Modbus
|
|
296
|
+
gateway reads one reply per request): hold the port until it goes away.
|
|
297
|
+
|
|
298
|
+
The stream library reads the port from the moment it opens and closes the
|
|
299
|
+
connection itself on an I/O error (an unplugged USB adapter, a failed write), so a
|
|
300
|
+
loss is noticed here even while no request is in flight, and raised so that run()
|
|
301
|
+
reopens the port. A request that only times out (a silent slave) is not a loss."""
|
|
302
|
+
closed = asyncio.ensure_future(writer.wait_closed())
|
|
303
|
+
# Never cancel that task (stop() cancels this one instead): it would cancel the
|
|
304
|
+
# stream's own close future, which close() waits on as well.
|
|
305
|
+
closed.add_done_callback(_consume_error)
|
|
306
|
+
await asyncio.wait((closed,))
|
|
307
|
+
raise closed.exception() or ConnectionError("serial EOF / device removed")
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def _rdev(ser: Any) -> Optional[int]:
|
|
311
|
+
"""The device number of an open POSIX port (None elsewhere, or for a stand-in)."""
|
|
312
|
+
if sys.platform == "win32":
|
|
313
|
+
return None
|
|
314
|
+
try:
|
|
315
|
+
return os.fstat(ser.fileno()).st_rdev or None
|
|
316
|
+
except (AttributeError, OSError, ValueError, TypeError):
|
|
317
|
+
return None
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
def explain(e: BaseException, settings: SerialSettings) -> Optional[portdiag.Note]:
|
|
321
|
+
"""portdiag.explain for the device ``settings`` opens (blocking: run it in a thread)."""
|
|
322
|
+
try:
|
|
323
|
+
device = serial_io.resolve_device(settings, portlist.recent())
|
|
324
|
+
except OSError: # (serial_io.ForeignDevice: nothing to add to its own text)
|
|
325
|
+
return None
|
|
326
|
+
return portdiag.explain(e, device)
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
class NoteLog:
|
|
330
|
+
"""Logs what to know about a port just opened (portdiag.Note) when it differs from what
|
|
331
|
+
was logged for the last open: a port that keeps refusing RS-485 says so once, not at
|
|
332
|
+
every reopen."""
|
|
333
|
+
|
|
334
|
+
def __init__(self, log: Callable[[str], None]) -> None:
|
|
335
|
+
self._log = log
|
|
336
|
+
self._last: tuple = ()
|
|
337
|
+
|
|
338
|
+
def __call__(self, notes: Iterable[Any]) -> None:
|
|
339
|
+
notes = tuple(notes)
|
|
340
|
+
for note in notes:
|
|
341
|
+
if note not in self._last:
|
|
342
|
+
self._log(f"serial warning: {note.text()}")
|
|
343
|
+
self._last = notes
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
async def close_stream(writer: asyncio.StreamWriter,
|
|
347
|
+
log: Optional[Callable[[str], None]] = None) -> None:
|
|
348
|
+
"""Close a serial port's stream, in at most about 2 x SERIAL_CLOSE_TIMEOUT_S.
|
|
349
|
+
|
|
350
|
+
What the port still has to send (the transport's buffer, the OS's output queue) gets
|
|
351
|
+
SERIAL_CLOSE_TIMEOUT_S to go out. What the device has not taken by then (CTS low, XOFF,
|
|
352
|
+
a PTY or virtual port nobody reads) is dropped, and ``log`` told how much. The port is
|
|
353
|
+
then closed at once: the stream's own graceful close waits for the OS to drain the port
|
|
354
|
+
(tcdrain, in an executor thread, without a time limit), which kept whoever closed it (a
|
|
355
|
+
mapping's stop() on a save, restart or shutdown) waiting while the device took nothing;
|
|
356
|
+
on some USB adapters that wait even outlived a purge of the output, and kept the
|
|
357
|
+
process from exiting."""
|
|
358
|
+
transport: Any = writer.transport
|
|
359
|
+
closed = asyncio.ensure_future(writer.wait_closed())
|
|
360
|
+
closed.add_done_callback(_consume_error)
|
|
361
|
+
if not transport.is_closing(): # (it is when an I/O error closed it already)
|
|
362
|
+
ser: Any = getattr(transport, "serial", None) # (a test's stand-in stream has none)
|
|
363
|
+
left = await _sent_within(transport, ser, SERIAL_CLOSE_TIMEOUT_S)
|
|
364
|
+
if left and not transport.is_closing():
|
|
365
|
+
with contextlib.suppress(Exception):
|
|
366
|
+
ser.reset_output_buffer() # what the OS holds: the close won't wait for it
|
|
367
|
+
if log is not None:
|
|
368
|
+
log(f"serial close: dropped {left} byte(s) the device did not take within "
|
|
369
|
+
f"{SERIAL_CLOSE_TIMEOUT_S:g} s")
|
|
370
|
+
if not transport.is_closing():
|
|
371
|
+
with contextlib.suppress(Exception):
|
|
372
|
+
transport.abort() # nothing left to send: close without the OS drain
|
|
373
|
+
await _done_within(closed, SERIAL_CLOSE_TIMEOUT_S)
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
async def sent_within(writer: asyncio.StreamWriter, seconds: float) -> int:
|
|
377
|
+
"""Wait until an open port has sent what was written to it (the transport's buffer and
|
|
378
|
+
the OS's output queue), at most ``seconds``; the bytes still waiting then."""
|
|
379
|
+
transport: Any = writer.transport
|
|
380
|
+
return await _sent_within(transport, getattr(transport, "serial", None), seconds)
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
async def _sent_within(transport: Any, ser: Any, seconds: float) -> int:
|
|
384
|
+
"""Wait until the port has sent what it holds, at most ``seconds`` (and only while the
|
|
385
|
+
transport is open); the bytes still waiting then, 0 when all is gone."""
|
|
386
|
+
loop = asyncio.get_running_loop()
|
|
387
|
+
deadline = loop.time() + seconds
|
|
388
|
+
while True:
|
|
389
|
+
left = _unsent(transport, ser)
|
|
390
|
+
if not left or transport.is_closing() or loop.time() >= deadline:
|
|
391
|
+
return left
|
|
392
|
+
await asyncio.sleep(_SENT_POLL_S)
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
def _unsent(transport: Any, ser: Any) -> int:
|
|
396
|
+
"""Bytes the transport holds plus those in the OS's output queue (an unplugged port
|
|
397
|
+
answers neither: 0)."""
|
|
398
|
+
n = 0
|
|
399
|
+
with contextlib.suppress(Exception):
|
|
400
|
+
n += int(transport.get_write_buffer_size())
|
|
401
|
+
with contextlib.suppress(Exception):
|
|
402
|
+
n += int(ser.out_waiting or 0)
|
|
403
|
+
return n
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
async def _done_within(fut: asyncio.Future, seconds: float) -> bool:
|
|
407
|
+
# asyncio.wait, not wait_for: a timeout must not cancel the stream's own close future
|
|
408
|
+
done, _pending = await asyncio.wait((fut,), timeout=seconds)
|
|
409
|
+
return bool(done)
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
def _consume_error(fut: asyncio.Future) -> None:
|
|
413
|
+
if not fut.cancelled():
|
|
414
|
+
fut.exception() # mark it seen: it is raised (or dropped on stop), not lost
|