Proxy Handlers¶
Handlers for the BlueSky data events the proxy subscribes to (see
WebATM.proxy.subscribers for the topic → handler mapping).
WebATM.proxy.handlers.simulation¶
WebATM.proxy.handlers.simulation ¶
Handle BlueSky simulation-state events (SIMINFO, ACDATA, STATECHANGE).
These handlers receive the core simulation feed from the BlueSky server: the
per-node simulation clock and state (SIMINFO), the aircraft traffic frames
(ACDATA), and explicit run-state transitions (STATECHANGE). They cache the data
on the proxy and forward it to connected browsers over Socket.IO as the
siminfo, acdata, and statechange events.
on_siminfo_received ¶
Process a BlueSky SIMINFO event and emit siminfo to web clients.
Updates the per-node status/clock tracking for every sending node (feeding
the Simulation Nodes panel via a throttled node_info emission), but only
caches and emits the header simulation info for the active node so the
displayed clock does not jump between nodes. Emissions to browsers are
throttled to proxy.siminfo_interval.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
speed
|
float
|
Simulation speed multiplier. |
required |
simdt
|
float
|
Simulation timestep in seconds. |
required |
simt
|
float
|
Elapsed simulation time in seconds. |
required |
simutc
|
str
|
Simulation UTC time string. |
required |
ntraf
|
int
|
Number of aircraft currently in the simulation. |
required |
state
|
int
|
Simulation run-state code. |
required |
scenname
|
str
|
Name of the currently loaded scenario. |
required |
sender_id
|
bytes | str | None
|
Identifier of the sending node; bytes are converted to a hex string. |
None
|
Source code in WebATM/proxy/handlers/simulation.py
on_acdata_received ¶
Process a BlueSky ACDATA traffic frame and emit acdata to web clients.
Hot path: the network timer delivers ACDATA at up to 50 Hz, but frames are
only serialized and cached at acdata_interval (10 Hz), only for the
active node, and only emitted to browsers while any are connected.
make_json_serializable is the dominant per-frame cost, so it is deferred
until after the active-node filter and the throttle accept the frame. The
cache is refreshed even with no browser attached — initial_data, the
backup timer and the ROUTEDATA filter serve it, so it must track the live
feed. Set WEBATM_PERF=1 (WebATM.proxy.perf) to measure the hot path.
Aircraft clearing on a simulation reset is NOT handled here: BlueSky signals a reset on the dedicated RESET topic (events.on_reset_received), never via an ACDATA action.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
Aircraft state arrays keyed by field ( |
required |
Source code in WebATM/proxy/handlers/simulation.py
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | |
on_statechange_received ¶
Process a BlueSky STATECHANGE event and emit statechange to web clients.
Updates the cached simulation state (proxy.sim_data['state']) and
immediately forwards the new run-state and sending node to connected
browsers, without throttling. Like SIMINFO, only the active node's state
changes touch the cached header state — a paused background node must not
flip the displayed run-state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
Event payload; the |
required |
sender_id
|
bytes | str | None
|
Identifier of the sending node; bytes are converted to a hex string. |
None
|
Source code in WebATM/proxy/handlers/simulation.py
WebATM.proxy.handlers.shapes¶
WebATM.proxy.handlers.shapes ¶
Handle BlueSky POLY shape events and split them into polygons and polylines.
BlueSky publishes all drawn shapes on a single POLY topic as shared-state
updates: the network client strips the [action, payload] wrapper and
records the action (Update/Delete/Replace/...) on its context before
dispatching here. This module applies each action to the per-node shape stores
on the proxy, separates polygons from polylines by their shape field, and
forwards the active node's shapes to browsers as the poly and polyline
Socket.IO events.
on_poly_received ¶
Process a BlueSky POLY event and emit poly/polyline to web clients.
Resolves the sending node and shared-state action from the BlueSky network context and applies the message to that node's stored shapes: Delete removes the named shapes, Replace/Reset/ActChange overwrite the stored sets, and updates merge into them (patching partial per-shape updates such as a colour change). At most the five most recent polygons and polylines are kept per node. The complete stored shape sets are emitted only when the sender is the currently active node.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
POLY payload from the BlueSky server (the shared-state
action wrapper is already stripped by the network client): a
|
required |
*args
|
Any
|
Extra positional arguments from the network dispatch (unused). |
()
|
**kwargs
|
Any
|
Extra keyword arguments from the network dispatch (unused). |
{}
|
Source code in WebATM/proxy/handlers/shapes.py
WebATM.proxy.handlers.commands¶
WebATM.proxy.handlers.commands ¶
Handle BlueSky stack-command events (STACK, STACKCMDS).
STACKCMDS carries the server's command dictionary, which is cached on the
proxy and forwarded to browsers as the cmddict Socket.IO event so the web
console can validate and autocomplete commands. STACK carries command lines
forwarded by the simulation — commands it did not recognize and assumes are
GUI/client commands (typically PAN/ZOOM lines in scenario files). They are
forwarded to browsers as stack_command events, where the frontend's
CommandHandler executes the ones it implements (PAN, ZOOM, ...) exactly as if
they had been typed into the console — matching BlueSky's own GUIs, which run
forwarded commands through their client stack. Nothing is ever sent back to
the server (that would loop: the simulation forwarded the line precisely
because it cannot execute it).
on_stackcmds_received ¶
Process a BlueSky STACKCMDS event and emit cmddict to web clients.
BlueSky publishes STACKCMDS with replace semantics: each node answers a REQUEST with a full Replace of its own command dictionary (plugins can register extra commands per node). The console sends commands to the active node, so only the active node's dictionary is accepted — a background node's answer must not overwrite (or leak commands into) the set the console validates against. A Replace action rebuilds the stored dictionary; other actions merge. Other payload shapes are only logged.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict | bytes | str
|
Unwrapped STACKCMDS shared-state payload; a
dict is expected to contain a |
required |
Source code in WebATM/proxy/handlers/commands.py
on_stack_received ¶
Process a BlueSky STACK event carrying sim-forwarded command lines.
Normalizes the payload to individual command lines — BlueSky's
stack.forward() joins multiple commands into one semicolon-separated
string, and its reference client splits them back apart (stack() in
bluesky.stack.stackbase), so the same split happens here — and
forwards each non-empty line to browsers via _forward_to_browsers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
str | list | tuple
|
One command line (possibly semicolon-joined), or a sequence of such lines. Other types are logged and ignored. |
required |
Source code in WebATM/proxy/handlers/commands.py
WebATM.proxy.handlers.echo¶
WebATM.proxy.handlers.echo ¶
Echo message handler for command responses.
echo ¶
Handle ECHO messages (command responses) from the simulation.
BlueSky's echo flags are an error bitmask (BS_ARGERR=1,
BS_FUNERR=2, BS_CMDERR=4 — see bluesky/__init__.py; its stack
only ever sets them on failed commands), while the web client renders
flags as severity levels (0 info, 1 error, 2 warning). Any set bit
therefore maps to the error level. Delegates to _echo_response, which
emits immediately — command responses are never throttled.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text
|
str
|
The echo text; newlines and formatting are preserved. |
required |
flags
|
int | None
|
BlueSky echo flags; nonzero marks an error. |
None
|
sender_id
|
bytes | str | None
|
ID of the node that sent the echo,
forwarded in the same hex form as |
None
|
Source code in WebATM/proxy/handlers/echo.py
WebATM.proxy.handlers.routes¶
WebATM.proxy.handlers.routes ¶
Route data handler for aircraft route visualization.
on_routedata_received ¶
Handle ROUTEDATA events carrying an aircraft's route.
Serializes the route and emits a routedata event to connected web
clients. Frames that carry waypoints are only forwarded when the aircraft
is part of the active node's traffic, preventing flicker when switching
between nodes. Waypoint-less frames are BlueSky's route-clear broadcasts
(route display toggled off, or the aircraft was deleted) and are always
forwarded — the aircraft they refer to may already be gone from the
traffic, and clients need them to drop their cached route.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
ROUTEDATA payload with the aircraft ID ( |
required |
Source code in WebATM/proxy/handlers/routes.py
WebATM.proxy.handlers.events¶
WebATM.proxy.handlers.events ¶
Event handlers for RESET and REQUEST events.
on_reset_received ¶
Handle RESET events from the BlueSky server.
Clears the stored polygon/polyline shapes for the node that sent the
reset. Browsers display the active node only, so when the resetting node
is the active one this also drops the cached aircraft and sim info and
emits the map-clearing acdata/poly/polyline payloads plus the
reset event — while a background node's reset must not wipe the active
node's display. When the sender or active node can't be resolved, the
reset is accepted so a single-node display still works (same fallback as
the SIMINFO/ACDATA active-node filter).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Any
|
Optional RESET payload (unused). |
None
|
*args
|
Any
|
Additional positional payload items (unused). |
()
|
sender_id
|
bytes | str | None
|
Node that reset, from the message header; bytes are converted to a hex string. The shared network context is deliberately not consulted — it holds the sender of the last shared-state message, not of this RESET. |
None
|
**kwargs
|
Any
|
Additional keyword payload items (unused). |
{}
|
Source code in WebATM/proxy/handlers/events.py
on_request_received ¶
Handle REQUEST events from the BlueSky server.
Currently only logs the payload; specific request handling is not yet implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Any
|
The REQUEST payload. |
required |
*args
|
Any
|
Additional positional payload items (unused). |
()
|
**kwargs
|
Any
|
Additional keyword payload items (unused). |
{}
|
Source code in WebATM/proxy/handlers/events.py
WebATM.proxy.handlers.visualization¶
WebATM.proxy.handlers.visualization ¶
Visualization handlers for PLOT, TRAILS, SHOWDIALOG, and SIMSETTINGS events.
All four are placeholders that only log their payload until visualization support is implemented in the web client. Their signatures accept any payload shape the client dispatches: shared-state topics (TRAILS, SIMSETTINGS) arrive as one positional dict, while event topics with dict payloads (PLOT, SHOWDIALOG) arrive as keyword arguments.
on_plot_received ¶
Log PLOT events; plot display is not yet implemented.
on_showdialog_received ¶
Log SHOWDIALOG events; web dialog display is not yet implemented.
on_simsettings_received ¶
Log SIMSETTINGS events; settings handling is not yet implemented.
on_trails_received ¶
Log TRAILS events; trail visualization is not yet implemented.
WebATM.proxy.handlers.navigation¶
WebATM.proxy.handlers.navigation ¶
Navigation handler for DEFWPT (Define Waypoint) events.
on_defwpt_received ¶
Log DEFWPT events; waypoint rendering is not yet implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Any
|
Unwrapped DEFWPT shared-state payload describing the waypoint(s). |
None
|
*args
|
Any
|
Additional positional payload items (unused). |
()
|
**kwargs
|
Any
|
Additional keyword payload items (unused). |
{}
|