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_budgetandeirprefuse a negative loss. A gain may be negative. - A
Budgethas.rx: Power,.margin: Gainand.ok, true when the margin is zero or more. Printed, it says whether the link closes. Power + Poweris refused by the check, because two dBm figures do not add.combineadds the powers in milliwatts: two signals of -3 dBm give about 0 dBm.
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_rateis 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.latitudeis 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.polarizationis"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_availabilityfinds 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_availabilitycannot 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.
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.
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:
delayis 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.
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.
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.
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.