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 engine computed it. Frames are store-and-forward: a bridge starts sending a frame only after it has received all of it. Propagation delay on the cable is not modelled.

Latency

For each frame instance: end of its window on the last hop minus start of its window on the first hop. 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.

When you press Run scheduler with the AutoTSN server selected, the studio sends one HTTP request. The endpoint and the access code come from Settings (the gear icon in the studio). The body is the project, reshaped: the format dates from AutoTSN v1, so some fields are fixed values kept for compatibility.

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  ·  10 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 3400 \
  sched-entry S 0x80 2400 \
  sched-entry S 0x7f 60200 \
  sched-entry S 0x00 15000 \
  sched-entry S 0x80 8000 \
  sched-entry S 0x7f 399400 \
  sched-entry S 0x00 15000 \
  sched-entry S 0x80 2400 \
  sched-entry S 0x7f 479200 \
  sched-entry S 0x00 15000 \
  flags 0x2

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 endpoint in the studio's Settings. The studio then sends every run to your scheduler and shows its result in the Gantt chart, checks latency and jitter, 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, select the AutoTSN server engine, and set the endpoint to http://127.0.0.1:8000.
• 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.

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