Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Telecom maths and optics

Radio and fibre budgets, rain, traffic, voice, optics.

All documentation pages

This page covers the telecom maths (radio, rain, fibre, traffic, voice), the optical readings of a device, and the names of DSCP marks and well-known ports. The maths works on the units of types and units, and needs no device.

Each function follows a named formula or recommendation, written in its help text. bogo doc NAME prints it. Every figure here is an estimate for planning. A measurement on the real link is the real answer.

Radio

Command Gives Formula
fspl(distance: Distance, freq: Frequency) Gain, the free-space loss as a positive figure ITU-R P.525: L = 32.44 + 20 log10(f MHz) + 20 log10(d km)
fresnel(distance: Distance, freq: Frequency, zone: int = 1) Distance, the radius of Fresnel zone zone at the middle of the hop ITU-R P.530, P.526: r = sqrt(n * wavelength * d / 4) at mid-hop
link_budget(tx: Power, gains: list[Gain], losses: list[Gain], sensitivity: Power) Budget rx = tx + sum(gains) - sum(losses); margin = rx - sensitivity
eirp(tx: Power, antenna: Gain, cable_loss: Gain) Power EIRP = tx - cable loss + antenna gain (ITU-R definition)
combine(a: Power, b: Power) Power, the sum of two powers added in milliwatts
  • A loss is given as a positive number. link_budget and eirp refuse a negative loss. A gain may be negative.
  • A Budget has .rx: Power, .margin: Gain and .ok, true when the margin is zero or more. Printed, it says whether the link closes.
  • Power + Power is refused by the check, because two dBm figures do not add. combine adds the powers in milliwatts: two signals of -3 dBm give about 0 dBm.
Bogolang
loss: Gain = fspl(12km, 18GHz)
b: Budget = link_budget(18dBm, [38dBi, 38dBi], [loss, 2dB], -70dBm)
print(b)
print(b.rx, b.margin, b.ok)
print(fresnel(10km, 5.8GHz))
print(eirp(20dBm, 24dBi, 1.5dB))
print(combine(-3dBm, -3dBm))

The output:

rx -47.137dBm, margin 22.863dB: the link closes
-47.137dBm 22.863dB True
11.368m
42.5dBm
0.01dBm

Rain

Command Gives
rain_fade(distance: Distance, freq: Frequency, rain_rate: float, polarization: str = 'horizontal') Gain, the loss rain adds for 0.01 percent of an average year
rain_availability(margin: Gain, distance: Distance, freq: Frequency, rain_rate: float, polarization: str = 'horizontal', *, latitude: float) Percent, the share of an average year the hop stays up against rain

The engineer gives the values tied to the place. Bogolang carries no rain map and assumes no place on Earth.

  • rain_rate is R0.01 in mm/h: the rain rate passed for 0.01 percent of the year at the site, from the ITU-R P.837 maps or from local records.
  • latitude is the latitude of the hop in degrees, north or south. It has no default. The ITU method has one form below 30 degrees and another from 30 degrees up, and no single value is fair to every engineer.
  • polarization is "horizontal" or "vertical".

The method:

  • Loss per km: gamma = k * R^alpha, with k and alpha from ITU-R P.838-3.
  • Effective length of the hop, from ITU-R P.530-12 section 2.4.1: r = 1 / (1 + d / d0), d0 = 35 exp(-0.015 R0.01) km, and A0.01 = gamma * d * r.
  • Other shares of the year, from ITU-R P.530-12: one formula at latitudes of 30 degrees or more, another below. rain_availability finds the share where the fade equals the margin.

Limits, as the code states them:

  • P.530-12 says the method holds at least up to 40 GHz and 60 km. Bogolang accepts 1 to 100 GHz and up to 60 km.
  • rain_availability cannot promise more than 99.999 percent: a larger margin gives 99.999. A margin below the fade at 1 percent of the year gives 99.0, which means 99 percent or less.
  • Both count rain only. They do not count multipath fading, obstruction or equipment failure.
Bogolang
fade: Gain = rain_fade(12km, 18GHz, 42.0, "vertical")
print(fade)
print(rain_availability(30dB, 12km, 18GHz, 42.0, "vertical", latitude=45.0))
print(rain_availability(30dB, 12km, 18GHz, 42.0, "vertical", latitude=10.0))
23.855dB
99.995pct
99.996pct

The rain rate 42.0 and the two latitudes are examples only.

A whole hop

The example radio_link puts these together for one 12 km hop at 18 GHz. Its output:

Hop site-a to site-b: 12km at 18GHz, vertical polarization
  Free-space loss     139.137dB
  First Fresnel zone  7.069m radius at mid-hop
  Received level      -47.137dBm
  Fade margin         22.863dB
  Rain fade (0.01%)   23.855dB at 42.0 mm/h
  Availability (rain) 99.989pct, about 59 min down a year
  Target 99.99pct: the hop misses the target

Fibre

Command Gives
fibre_loss(distance: Distance, wavelength: Wavelength, connectors: int, splices: int, *, per_km: Gain \| None = None, per_connector: Gain = 0.5dB, per_splice: Gain = 0.1dB) Gain, the planned loss of the run

The method is the loss budget of TIA-568 and IEC 61280-4: km * per_km + connectors * per_connector + splices * per_splice.

Without per_km, the loss per km comes from the wavelength, within 15 nm either side:

Wavelength dB per km Fibre
850 nm 3.0 multimode
1300 nm 1.0 multimode
1310 nm 0.35 single-mode
1550 nm 0.22 single-mode
1625 nm 0.25 single-mode

1300 and 1310 overlap: the nearer one is used, and 1305 nm counts as 1300 (multimode). Giving per_km removes the doubt. Another wavelength with no per_km is an error. These are planning values. The real loss is what a light source and power meter, or an OTDR, measures.

Bogolang
print(fibre_loss(12km, 1310nm, connectors=2, splices=6))
print(fibre_loss(30km, 1550nm, 2, 10, per_km=0.25dB, per_connector=0.75dB))
5.8dB
10dB

Traffic and voice

Command Gives Formula
erlang_b(traffic: Traffic, lines: int) Percent, the share of calls blocked Erlang B, by the stable recurrence of ITU-T E.520 and the ITU-D Teletraffic Engineering Handbook
erlang_c(traffic: Traffic, agents: int) Percent, the share of calls that wait Erlang C from Erlang B: C = N * B / (N - A * (1 - B)). When the traffic is equal to or above the agents, 100 percent
mos(loss: Percent, delay: Duration, jitter: Duration, codec: str) float, estimated call quality from 1.0 to 4.5 ITU-T G.107 E-model, simplified form (Cole and Rosenbluth, 2001), Ie and Bpl from ITU-T G.113 Appendix I
codec_bandwidth(codec: str, layer: str = 'ip') Rate, one call in one direction (payload + headers) * 8 * packets per second

Traffic is written in erlangs: 10erl.

About mos:

  • delay is one way. Twice the jitter is added for the jitter buffer, and the delay of the codec itself.
  • Codecs: G.711, G.722, G.723.1, G.726, G.729A. Usual spellings are read too: g711, pcmu, pcma, g729, g729ab. Another name is an error that lists the known ones.
  • G.722 is scored as G.711. G.726 has no loss figure in G.113, so it uses G.711's: its score is optimistic.
  • It is an estimate from a simplified model, not a measurement.

About codec_bandwidth:

  • layer="ip" counts 40 bytes of IP, UDP and RTP headers. layer="ethernet" adds 18 bytes (14 of header and 4 of FCS).
  • Packets are 20 ms apart, 30 ms for G.723.1, as in Cisco's "Voice Over IP: Per Call Bandwidth Consumption".
  • The figure of G.723.1 was not checked against a published table.
Bogolang
print(erlang_b(10erl, 15))
print(erlang_c(10erl, 12))
print(mos(1pct, 80ms, 10ms, "G.711"))
print(mos(1pct, 80ms, 10ms, "g729"))
print(codec_bandwidth("G.711"))
print(codec_bandwidth("G.711", layer="ethernet"))
print(codec_bandwidth("G.729"))
3.65pct
44.939pct
4.26
3.83
80kbps
87.2kbps
24kbps

Optical readings

Command Gives
optics(d: Device) list[OpticReading], one per port with a transmit or receive reading, sorted by port

It opens one read-only session and sends one command:

Platform Command
ios, iosxe show interfaces transceiver detail
junos show interfaces diagnostics optics \| display xml

Another platform is refused with a sentence that names the platforms that work.

Field Type What it holds
.port Intf The port
.tx, .rx Power \| None Transmit and receive levels
.temperature float \| None Degrees Celsius
.rx_low, .rx_high, .tx_low, .tx_high Power \| None The device's own low and high alarm limits
.status str "ok", "low", "high", "no light" or "unknown"
.lane int \| None The lane of a multi-lane optic on Junos; empty otherwise

How the status is found:

  • It compares the receive level with the device's own alarm limits. A level exactly on a limit is "ok".
  • "no light" is a receive level of -40 dBm or less.
  • "unknown": no receive reading, or the device gives no limits.
  • A port with no optical reading is left out.
Bogolang
sw1: Device = Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")
readings: list[OpticReading] = optics(sw1)
table(readings, ["port", "tx", "rx", "rx_low", "rx_high", "temperature", "status"])
for r in readings:
    if r.status != "ok":
        print(f"{r.port}: {r.status}, rx {r.rx}")

Run with --replay on a saved output written for the tests:

port      tx       rx        rx_low    rx_high  temperature  status
--------  -------  --------  --------  -------  -----------  --------
Te1/1/1   -2.4dBm  -3.1dBm   -13.9dBm  2dBm            32.3  ok
Te1/1/2   -2.2dBm  -40dBm    -13.9dBm  2dBm            30.1  no light
Te1/1/3   -2.6dBm  -15.2dBm  -13.9dBm  2dBm            35.8  low
Te1/1/4   -1.9dBm  2.6dBm    -13.9dBm  2dBm              41  high
Te1/1/10  -3dBm    -5dBm                               29.5  unknown
Te1/1/2: no light, rx -40dBm
Te1/1/3: low, rx -15.2dBm
Te1/1/4: high, rx 2.6dBm
Te1/1/10: unknown, rx -5dBm

optics has never read a real device. Its readers were written from the documented forms of the two commands. Another release may word its table headers differently, and would then give no readings. See not proven.

Markings and ports

Command Gives
dscp(name: str) int: the DSCP value of a name, in any case
dscp_name(value: int) str: the name of a value from 0 to 63; a value with no name gives its number
port_of(name: str) int: the well-known port of a service name, in any case
service_of(port: int) str: the main service name of a well-known port

DSCP names: EF (46), AF11 to AF43, CS0 to CS7, default (or BE) and VA (or VOICE-ADMIT, 44). The value 0 is named default on the way back. A name that is not in the list is an error that lists the names.

The ports come from a fixed table taken from the IANA registry, so every machine gives the same answer. It holds about 40 services, such as ssh, snmp, snmptrap, bgp, syslog, radius, sip. Some have a second name: dns or domain, http or www. A name or a port not in the table is an error.

Bogolang
print(dscp("EF"), dscp("af41"), dscp("BE"))
print(dscp_name(46), dscp_name(34), dscp_name(0), dscp_name(5))
print(port_of("SSH"), port_of("snmptrap"), service_of(443), service_of(53))
46 34 0
EF AF41 default 5
22 162 https dns

ping, ping_all and trace take a DSCP value to mark their probes, for example ping(192.0.2.10, dscp=dscp("EF")). See reach.