Sections de la documentation

Calculateur de bilan de liaison 5G NR — affaiblissement 3GPP TR 38.901, SINR et portée

POSThttps://rftools.io/api/py/v1/calculate

Slug 5g-nr-link-budget. Un bilan de liaison 5G NR sur les modèles de canal du 3GPP : affaiblissement de propagation TR 38.901 en macrocellule rurale, macrocellule urbaine, microcellule urbaine et bureau en intérieur, LOS ou NLOS, plancher de bruit déduit des blocs de ressources, SINR, marge de liaison, portée maximale dans le domaine de validité du modèle et débit crête TS 38.306.

Entrées

Envoyez chacune de ces entrées dans inputs, dans les unités indiquées. La plupart sont obligatoires : un appel auquel il en manque une est refusé (400) et ne coûte rien ; une entrée dont le calculateur peut se passer prend la valeur par défaut indiquée. Une entrée hors de sa plage est tout de même calculée et signalée dans la provenance.

Entrées de 5g-nr-link-budget
Nom	Unité	Plage	Valeur par défaut	Description
scenarionombre	aucune	0 … 3	1	Déploiement 3GPP TR 38.901 : 0 macrocellule rurale, 1 macrocellule urbaine, 2 microcellule urbaine en canyon de rue, 3 bureau en intérieur
lineOfSightnombre	aucune	0 … 1	0	Indique si le trajet direct est dégagé ; en NLOS, le calcul retient la plus grande des formules LOS et NLOS
frequencynombre	GHz	au moins 0.1	3.5	Fréquence centrale ; TR 38.901 couvre de 0,5 à 100 GHz (30 GHz pour RMa)
channelBandwidthnombre	MHz	au moins 3	100	Largeur de bande du canal de l'UE ; fixe les blocs de ressources, donc la largeur de bande de bruit
scsnombre	kHz	au moins 15	30	15, 30 ou 60 kHz en FR1 ; 60 ou 120 kHz en FR2
bsHeightnombre	m	au moins 1	25	TR 38.901 fixe 25 m pour UMa et 10 m pour UMi ; RMa couvre de 10 à 150 m
utHeightnombre	m	au moins 0.5	1.5	Hauteur du terminal utilisateur ; 1,5 m au niveau de la rue
distancenombre	m	au moins 1	500	Distance au sol entre la station de base et l'utilisateur
txPowernombre	dBm	quelconque	46	Puissance conduite totale sur la porteuse (46 dBm correspondent à 40 W)
txGainnombre	dBi	quelconque	17	Gain de l'antenne d'émission
rxGainnombre	dBi	quelconque	0	Gain de l'antenne de réception
lossesnombre	dB	au moins 0	3	Pertes câble, corps et autres
shadowMarginnombre	dB	au moins 0	8	Marge réservée à l'effet de masque ; à comparer à la sortie σ_SF du scénario
noiseFigurenombre	dB	au moins 0	7	Facteur de bruit du récepteur
requiredSinrnombre	dB	quelconque	0	SINR nécessaire à la modulation et au codage choisis
interferenceMarginnombre	dB	au moins 0	3	Remontée du bruit plus interférences au-dessus du bruit thermique
layersnombre	aucune	1 … 8	4	Couches MIMO
modulationOrdernombre	aucune	1 … 10	8	Ordre de modulation (bits par symbole)
scalingFactornombre	aucune	0.1 … 1	1	Facteur d'échelle de capacité de l'UE dans TS 38.306 : 1, 0,8, 0,75 ou 0,4
linkDirectionnombre	aucune	0 … 1	0	Fixe le surdébit de TS 38.306 : 0,14 en DL et 0,08 en UL en FR1, 0,18 et 0,10 en FR2
extraLossCountnombre	aucune	0 … 6	0	Nombre de pertes supplémentaires sur le lien, par exemple l'entrée dans un bâtiment, la végétation, le corps ou un désaccord de polarisation (0–6)
extraLoss1nombre	dB	0 … 50	0	Une perte supplémentaire sur le lien, par exemple l'entrée dans un bâtiment, la végétation, l'absorption par le corps ou un désaccord de polarisation
extraLoss2nombre	dB	0 … 50	0	Une perte supplémentaire sur le lien, par exemple l'entrée dans un bâtiment, la végétation, l'absorption par le corps ou un désaccord de polarisation
extraLoss3nombre	dB	0 … 50	0	Une perte supplémentaire sur le lien, par exemple l'entrée dans un bâtiment, la végétation, l'absorption par le corps ou un désaccord de polarisation
extraLoss4nombre	dB	0 … 50	0	Une perte supplémentaire sur le lien, par exemple l'entrée dans un bâtiment, la végétation, l'absorption par le corps ou un désaccord de polarisation
extraLoss5nombre	dB	0 … 50	0	Une perte supplémentaire sur le lien, par exemple l'entrée dans un bâtiment, la végétation, l'absorption par le corps ou un désaccord de polarisation
extraLoss6nombre	dB	0 … 50	0	Une perte supplémentaire sur le lien, par exemple l'entrée dans un bâtiment, la végétation, l'absorption par le corps ou un désaccord de polarisation

Sorties

Renvoyées dans values, par nom. Une valeur non bornée ou non définie vaut null.

Sorties de 5g-nr-link-budget
Champ	Unité	Description
linkMarginprincipale	dB	Marge de liaison
pathLoss	dB	Affaiblissement de propagation (TR 38.901)
receivedPower	dBm	Puissance reçue
sinr	dB	SINR (médian)
maxPathLoss	dB	Affaiblissement maximal admissible
maxRange	m	Portée maximale (2-D, dans le domaine de validité du modèle)
resourceBlocks	aucune	Blocs de ressources (N_RB)
occupiedBandwidth	MHz	Bande occupée (N_RB × 12 × SCS)
thermalNoise	dBm	Bruit thermique (kTB)
noiseFloor	dBm	Plancher de bruit du récepteur (kTB + NF)
breakpointDistance	m	Distance de point de rupture
shadowFadingStd	dB	Écart type de l'effet de masque (σ_SF)
peakDataRate	Mbps	Débit crête (TS 38.306)
totalLoss	dB	Perte totale

Comment l'appeler

Calculer : un appel, la requête et la réponse complètes, et ses erreurs.
Calcul par lots : ce calculateur avec d'autres, ou un balayage, en une seule requête.
Résoudre pour une valeur cible : la valeur d'une entrée qui amène une sortie à une cible.

curl -X POST https://rftools.io/api/py/v1/calculate \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "5g-nr-link-budget",
    "inputs": {
      "scenario": 1,
      "lineOfSight": 0,
      "frequency": 3.5,
      "channelBandwidth": 100,
      "scs": 30,
      "bsHeight": 25,
      "utHeight": 1.5,
      "distance": 500,
      "txPower": 46,
      "txGain": 17,
      "rxGain": 0,
      "losses": 3,
      "shadowMargin": 8,
      "noiseFigure": 7,
      "requiredSinr": 0,
      "interferenceMargin": 3,
      "layers": 4,
      "modulationOrder": 8,
      "scalingFactor": 1,
      "linkDirection": 0,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "extraLoss5": 0,
      "extraLoss6": 0
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

result = client.calculate("5g-nr-link-budget", {
    "scenario": 1,
    "lineOfSight": 0,
    "frequency": 3.5,
    "channelBandwidth": 100,
    "scs": 30,
    "bsHeight": 25,
    "utHeight": 1.5,
    "distance": 500,
    "txPower": 46,
    "txGain": 17,
    "rxGain": 0,
    "losses": 3,
    "shadowMargin": 8,
    "noiseFigure": 7,
    "requiredSinr": 0,
    "interferenceMargin": 3,
    "layers": 4,
    "modulationOrder": 8,
    "scalingFactor": 1,
    "linkDirection": 0,
    "extraLossCount": 0,
    "extraLoss1": 0,
    "extraLoss2": 0,
    "extraLoss3": 0,
    "extraLoss4": 0,
    "extraLoss5": 0,
    "extraLoss6": 0,
})
print(result.values)
print(result.warnings, result.provenance.formula_ref)

const response = await fetch("https://rftools.io/api/py/v1/calculate", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slug": "5g-nr-link-budget",
    "inputs": {
      "scenario": 1,
      "lineOfSight": 0,
      "frequency": 3.5,
      "channelBandwidth": 100,
      "scs": 30,
      "bsHeight": 25,
      "utHeight": 1.5,
      "distance": 500,
      "txPower": 46,
      "txGain": 17,
      "rxGain": 0,
      "losses": 3,
      "shadowMargin": 8,
      "noiseFigure": 7,
      "requiredSinr": 0,
      "interferenceMargin": 3,
      "layers": 4,
      "modulationOrder": 8,
      "scalingFactor": 1,
      "linkDirection": 0,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "extraLoss5": 0,
      "extraLoss6": 0
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "slug": "5g-nr-link-budget",
	  "inputs": {
	    "scenario": 1,
	    "lineOfSight": 0,
	    "frequency": 3.5,
	    "channelBandwidth": 100,
	    "scs": 30,
	    "bsHeight": 25,
	    "utHeight": 1.5,
	    "distance": 500,
	    "txPower": 46,
	    "txGain": 17,
	    "rxGain": 0,
	    "losses": 3,
	    "shadowMargin": 8,
	    "noiseFigure": 7,
	    "requiredSinr": 0,
	    "interferenceMargin": 3,
	    "layers": 4,
	    "modulationOrder": 8,
	    "scalingFactor": 1,
	    "linkDirection": 0,
	    "extraLossCount": 0,
	    "extraLoss1": 0,
	    "extraLoss2": 0,
	    "extraLoss3": 0,
	    "extraLoss4": 0,
	    "extraLoss5": 0,
	    "extraLoss6": 0
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/calculate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "slug": "5g-nr-link-budget",
  "values": {
    "linkMargin": 6.134701907799126,
    "pathLoss": 129.9158338083485,
    "receivedPower": -69.91583380834851,
    "sinr": 14.13470190779914,
    "maxPathLoss": 136.05053571614764,
    "maxRange": 718.1162910484755,
    "resourceBlocks": 273,
    "occupiedBandwidth": 98.28,
    "thermalNoise": -94.05053571614765,
    "noiseFloor": -87.05053571614765,
    "breakpointDistance": 560.3876799328955,
    "shadowFadingStd": 6,
    "peakDataRate": 2337.00012,
    "totalLoss": 132.9158338083485
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:5g-nr-link-budget",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "3GPP TR 38.901 V17.0.0, Table 7.4.1-1; TS 38.101-1 V18.15.0 Table 5.3.2-1; TS 38.306 V18.11.0, §4.1.2",
    "assumptions": [
      {
        "code": "tr38901-median-path-loss",
        "text": "Path loss is the median of the 3GPP TR 38.901 V17.0.0 Table 7.4.1-1 model for the chosen scenario and line-of-sight state; shadowing is covered only by the margin entered, and the LOS probability is not applied."
      },
      {
        "code": "effective-environment-height",
        "text": "UMa and UMi use an effective environment height of 1 m, and RMa the default building height of 5 m and street width of 20 m."
      },
      {
        "code": "exact-speed-of-light",
        "text": "Breakpoint distances use c = 299792458 m/s, where TR 38.901 writes 3.0×10⁸ m/s."
      }
    ],
    "validRange": {
      "status": "inside",
      "bounds": {
        "scenario": {
          "min": 0,
          "max": 3,
          "unit": ""
        },
        "lineOfSight": {
          "min": 0,
          "max": 1,
          "unit": ""
        },
        "frequency": {
          "min": 0.1,
          "max": null,
          "unit": "GHz"
        },
        "channelBandwidth": {
          "min": 3,
          "max": null,
          "unit": "MHz"
        },
        "scs": {
          "min": 15,
          "max": null,
          "unit": "kHz"
        },
        "bsHeight": {
          "min": 1,
          "max": null,
          "unit": "m"
        },
        "utHeight": {
          "min": 0.5,
          "max": null,
          "unit": "m"
        },
        "distance": {
          "min": 1,
          "max": null,
          "unit": "m"
        },
        "txPower": {
          "min": null,
          "max": null,
          "unit": "dBm"
        },
        "txGain": {
          "min": null,
          "max": null,
          "unit": "dBi"
        },
        "rxGain": {
          "min": null,
          "max": null,
          "unit": "dBi"
        },
        "losses": {
          "min": 0,
          "max": null,
          "unit": "dB"
        },
        "shadowMargin": {
          "min": 0,
          "max": null,
          "unit": "dB"
        },
        "noiseFigure": {
          "min": 0,
          "max": null,
          "unit": "dB"
        },
        "requiredSinr": {
          "min": null,
          "max": null,
          "unit": "dB"
        },
        "interferenceMargin": {
          "min": 0,
          "max": null,
          "unit": "dB"
        },
        "layers": {
          "min": 1,
          "max": 8,
          "unit": ""
        },
        "modulationOrder": {
          "min": 1,
          "max": 10,
          "unit": ""
        },
        "scalingFactor": {
          "min": 0.1,
          "max": 1,
          "unit": ""
        },
        "linkDirection": {
          "min": 0,
          "max": 1,
          "unit": ""
        },
        "extraLossCount": {
          "min": 0,
          "max": 6,
          "unit": ""
        },
        "extraLoss1": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss2": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss3": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss4": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss5": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        },
        "extraLoss6": {
          "min": 0,
          "max": 50,
          "unit": "dB"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "scenario": 1,
      "lineOfSight": 0,
      "frequency": 3.5,
      "channelBandwidth": 100,
      "scs": 30,
      "bsHeight": 25,
      "utHeight": 1.5,
      "distance": 500,
      "txPower": 46,
      "txGain": 17,
      "rxGain": 0,
      "losses": 3,
      "shadowMargin": 8,
      "noiseFigure": 7,
      "requiredSinr": 0,
      "interferenceMargin": 3,
      "layers": 4,
      "modulationOrder": 8,
      "scalingFactor": 1,
      "linkDirection": 0,
      "extraLossCount": 0,
      "extraLoss1": 0,
      "extraLoss2": 0,
      "extraLoss3": 0,
      "extraLoss4": 0,
      "extraLoss5": 0,
      "extraLoss6": 0
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": [
        "body",
        "inputs",
        "scenario"
      ],
      "msg": "Input should be a valid number, unable to parse string as a number",
      "input": "abc"
    }
  ]
}

Une entrée envoyée sous forme de texte. Rien n'a été décompté.

{
  "detail": "More than 120 requests in 60 seconds from this address.",
  "errorKind": "rate_limited",
  "limit": 120,
  "windowSeconds": 60,
  "upgradeUrl": "https://rftools.io/pricing/"
}

Trop de requêtes en une minute, avec Retry-After.

Les mêmes entrées sur la page du calculateurCalculateur de bilan de liaison 5G NR — affaiblissement 3GPP TR 38.901, SINR et portée, avec ces valeurs