The AutoTSN network model

A network in AutoTSN is a set of devices with numbered ports, links between two ports, and streams: periodic frames from one talker to one listener along a fixed route. A scheduler turns that into a transmission window for every frame on every link it crosses, and the studio turns the windows into IEEE 802.1Qbv gate control lists. Four JSON documents carry the model through those steps:

1. 01Project file.autotsn.jsonThe network as you drew it: devices, ports, links and streams with their routes.
2. 02Scheduler requestHTTP POST, JSONThe same network, in the shape the scheduling service reads.
3. 03Scheduler responseJSONA transmission window for every frame on every link it crosses.
4. 04Gate control liststaprio · YANG · JSONThe windows as IEEE 802.1Qbv gate schedules, per egress port.

Units and conventions

• Devices are referred to by their name (id) everywhere: in links, in streams and in routes. Names are unique.
• Ports are named p0 to p15. In the scheduler request and the gate control lists a port is written device-port, e.g. sw0-p1.
• Links are full duplex. A link direction is written (u,v): frames leaving u towards v. Both directions are scheduled independently.
• A schedule repeats every cycle. The cycle is the least common multiple of all stream periods (the hyperperiod), or a multiple of it if a scheduler plans a longer horizon.

Two end stations and a camera on two switches. The camera link runs at 100 Mbit/s, the others at 1 Gbit/s. Stream S1 is a 300-byte control frame every 500 µs; S2 a 1000-byte camera frame every millisecond. The documents below are generated by the studio's own code from this network, so they are exactly what you would get.

The project file is the complete model. It is what Project → Save project file writes and Project → Open project file reads. Its top level:

Devices

Every entry of nodes is a device. Its kind decides its role: bridges forward frames; end stations talk and listen. End stations may still appear in the middle of a route, for daisy-chained devices with a built-in switch.

Links

Every entry of edges is one cable between a port of one device and a port of another. source and target only record how the cable was drawn; frames use it in both directions.

• A port takes exactly one cable.
• Two devices are connected by at most one cable, and no device is linked to itself.
• A port index is always lower than the device's port count.

A stream is one frame of size bytes that the talker sends every period, to exactly one listener, along route. The route is part of the model: a scheduler places frames on it and does not choose paths. When you add a stream, the studio lists the simple paths between talker and listener, shortest first.

How latency and jitter are measured

The studio checks every schedule with the same definitions, whichever scheduler computed it, and every scheduler plans with the same delays. Frames are store-and-forward: a device sends a frame on only after it has arrived completely, that is after the end of its previous window plus the cable's propagation delay (length / 200 m/µs). On top of that it needs its bridge delay (processingDelay) and keeps its clock margin (precision); both are 1 µs by default.

Latency

For each frame instance: end of its window on the last hop, plus that cable's propagation delay, minus the start of its window on the first hop, plus the clock margins of talker and listener. The stream meets its bound if the largest value over all instances in the cycle is at most latency.

Jitter

How far consecutive frames drift from the period: the largest |start_k − start_k−1 − period|, taken on the first hop and on the last hop. 0 means every frame is sent and delivered at exactly the same offset in its period.

Egress queue

All scheduled streams share one queue per port, so frames of different streams must never wait in it at the same time. A forwarded frame counts as waiting from its complete arrival minus the device's clock margin until the start of its next window plus that margin; a frame the device sends itself, at the instant its window opens. A frame also has to leave before the next frame of its own stream arrives.

Within the period (optional)

By default a frame may still be on its way when the next one is sent, as long as it meets its latency bound. A stream with withinPeriod set is sent and delivered within one period instead: the k-th frame of the cycle between the start of the k-th period and the start of the next, clock margins of talker and listener included. Use it for control loops that run in step with the network cycle.

When you press Run scheduler with the server option selected, the studio sends one HTTP request. The address and the access code come from Settings, under Scheduling server (the gear icon in the studio): the AutoTSN server by default, or your own scheduler. The body is the project, reshaped: the format dates from AutoTSN v1, and fields marked fixed always carry the value shown.

POST https://api.autotsn.de/scheduler
Content-Type: application/json
 
{ "graph": { "nodes": [ … ], "edges": [ … ] }, "streams": [ … ], "userpass": "…", "numofqueues": 0, "numofwindows": 0 }

graph.nodes[]: one per device

graph.edges[]: one per link

streams[]: one per stream

For example, stream S1 of the worked example becomes messageSize 300, period 500, maxLatency 100, maxJitter 5 and routes [["es0", "sw0", "sw1", "es1"]].

The scheduler answers with JSON. Only the fields below are read; anything else is ignored. HTTP 401 or 403 means the access code was refused, 503 that the service is busy; any other error status is shown as a failed run.

• A window is the time the frame is on the wire on that link direction: from its first to its last bit, so its length is the transmission time at the link's line rate.
• Give one window per frame instance in the cycle: a stream with a 500 µs period in a 1 ms cycle has two windows on each of its links.
• Windows on the same link direction must not overlap.
• The cycle the studio uses is the smallest multiple of the hyperperiod that covers every window.

{
  "status": "infeasible",
  "message": "No feasible schedule exists for these streams."
}

From the windows, the studio builds one gate control list per egress port that carries scheduled frames. Each entry opens a set of gates (traffic classes, PCP 0–7) for a time interval. Scheduled windows open the time-aware traffic classes (PCP 7 by default, changeable in step 4); Autofill gives the remaining time to the other classes and puts a guard band, with all gates closed, before every time-aware window so no best-effort frame is still on the wire when it opens.

The gate mask has bit n set when the gate of traffic class n is open: 0x80 opens only PCP 7, 0x7f opens PCP 0–6, 0x00 closes everything. Traffic classes map one-to-one to PCP values.

Export formats

# sw0 → sw1  ·  cycle 1000000 ns  ·  9 entries
tc qdisc replace dev sw0-p1 parent root handle 100 stab overhead 24 taprio \
  num_tc 8 \
  map 0 1 2 3 4 5 6 7 0 0 0 0 0 0 0 0 \
  queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \
  base-time 0 \
  sched-entry S 0x00 4900 \
  sched-entry S 0x80 2400 \
  sched-entry S 0x7f 482600 \
  sched-entry S 0x00 15000 \
  sched-entry S 0x80 2400 \
  sched-entry S 0x7f 469000 \
  sched-entry S 0x00 15000 \
  sched-entry S 0x80 8000 \
  sched-entry S 0x00 700 \
  flags 0x2

Frame priority per stream

A gate list only does what it says if every talker tags its frames with the right priority. The JSON export therefore lists, for every stream, the PCP its talker must use; the taprio script and the YANG XML carry the same table as a comment. The studio configures gates, not talkers: setting the PCP on each sending device is up to you.

Normally every stream is scheduled. With “Schedule all streams”, the local scheduler can also produce shared streams: streams that found no room for windows of their own. They are sent one class lower, in the gaps that Autofill opens, and the studio computes guaranteed worst-case bounds for their latency and jitter. Those bounds assume that nothing else uses the shared or the time-aware class on that link; traffic that does, such as time sync frames, is declared in the studio's settings or per link (data.sharedBg).

Forwarding entries

Gate lists only work if every frame takes the route it was scheduled on. In a network with loops, Ethernet would choose the path itself (address learning and spanning tree), so the studio also gives every switch one static entry per stream: frames with this destination address and VLAN leave on this port. A stream is identified by its mac and vlan: by default each stream gets its own address from 91:E0:F0:00:00:01 on and VLAN 1 (Settings can choose another VLAN for all streams, or an own VLAN per stream), or it uses the listener's MAC: the MAC of the listener's port it arrives on (data.portMacs), else the device MAC. Every export includes the entries and the VLANs each port must carry, unless they are switched off in the export dialog. In a network with loops, the stream VLANs have to be taken out of spanning-tree control on the switches; the static entries keep the routes loop-free.

There are two ways to bring a network from AutoTSN Studio to another scheduler.

1. Read the project file

Save the project and read it in any language. Everything a scheduler needs is in edges and streams; the transmission time of a frame on a hop is ⌈size · 8000 / line rate⌉ ns.

import json, math
 
model = json.load(open("two-switch-line.autotsn.json"))
 
# Line rate per direction in Mbit/s. Every cable is full duplex.
rate = {}
for link in model["edges"]:
    a, b, mbps = link["source"], link["target"], link["data"]["bandwidth"]
    rate[a, b] = rate[b, a] = mbps
 
for s in model["streams"]:
    hops = list(zip(s["route"], s["route"][1:]))
    tx_ns = [math.ceil(s["size"] * 8000 / rate[h]) for h in hops]
    print(f'{s["id"]}: one frame every {s["period"]} µs over {hops}')
    print(f'    transmission per hop {tx_ns} ns, deadline {s["latency"]} µs')

2. Plug your scheduler into the studio

Serve the request and response described above over HTTP, and enter your URL as the address under Scheduling server in the studio's Settings. The server option in step 3 then reads Your server, and every run goes from the browser straight to your scheduler, not through ours. The studio shows the result in the Gantt chart, checks it frame by frame, and builds gate control lists from it. The stub below shows the protocol in about 40 lines of standard-library Python.

# A stub that speaks the AutoTSN scheduler protocol. It is not a real scheduler:
# it sends every stream's first frame once, back to back, and ignores periods.
import json, math
from http.server import BaseHTTPRequestHandler, HTTPServer
 
def schedule(req):
    rate = {}
    for e in req["graph"]["edges"]:
        rate[e["from"], e["to"]] = rate[e["to"], e["from"]] = e["bandwidth"]
    groups, t = {}, 0
    for s in req["streams"]:
        route = s["routes"][0]
        for u, v in zip(route, route[1:]):
            tx = math.ceil(s["messageSize"] * 8000 / rate[u, v])   # ns
            groups.setdefault(f"({u},{v})", []).append(
                {"label": s["name"], "data": [{"timeRange": [t, t + tx]}]})
            t += tx
    return {"status": "feasible",
            "timeline": [{"group": g, "data": d} for g, d in groups.items()]}
 
class Handler(BaseHTTPRequestHandler):
    def cors(self):
        self.send_header("Access-Control-Allow-Origin", "*")
        self.send_header("Access-Control-Allow-Methods", "POST, OPTIONS")
        self.send_header("Access-Control-Allow-Headers", "Content-Type")
 
    def do_OPTIONS(self):
        self.send_response(204)
        self.cors()
        self.end_headers()
 
    def do_POST(self):
        req = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        body = json.dumps(schedule(req)).encode()
        self.send_response(200)
        self.cors()
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)
 
HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()

• Run it with python3 stub_scheduler.py, open Settings, set the address to http://127.0.0.1:8000 and press Test connection: it sends a network with one stream and tells you whether the request got through, the answer has the right format, and the schedule passes the check. Then select Your server in step 3.
• The studio calls your scheduler from the browser, so it must answer CORS preflight requests (the do_OPTIONS above) and allow the origin of the studio.
• Browsers may ask for your permission before a website talks to a server on your own computer or local network. Allow it for this site.
• A scheduler on another machine should use HTTPS; browsers block plain HTTP requests from an HTTPS page.
• The check uses the timing model above: cable delay, bridge delay and clock margins between hops, the egress queue, and the latency and jitter definitions. A schedule that leaves one of them out is shown with the problems found.

Machine-readable definitions of the three documents (JSON Schema, draft 2020-12), to validate files and generate types. The project file names the format version it was written with in its format field.

• Project filenodes, edges, streamsautotsn-project.schema.json
• Scheduler requestwhat the studio sendsautotsn-scheduler-request.schema.json
• Scheduler responsewhat a scheduler answersautotsn-scheduler-response.schema.json