Satellite toolbox version 2025-12-19*This document is based on the latest test release.
Features may not be present in your current installed software. You may check their availability in your release documentation.
If you require an up to date release, ask for it in a ticket.
Features may not be present in your current installed software. You may check their availability in your release documentation.
If you require an up to date release, ask for it in a ticket.
Table of Contents
1 Introduction
ltesat is a companion software of Amarisoft eNB/gNB for any NTN scenario and features two main functions:
1.1 Toolbox mode
It can be used ’offline’ like a toolbox to replay or plan any satellite orbit. It accepts various inputs for satellite description which are compatible with eNB/gNB NTN configuration and can output the satellite trajectory with several formats: azimuth/elevation from a given ground position, groundtrack or ECEF coordinates.
It can also be used as a pass predictor over a given ground position.
It can also export a given satellite description to another format, e.g to generate a TLE file.
1.2 Mission control mode
Secondly, it can be used as a ’mission control’ software to control several Amarisoft eNB/gNB working with a worldwide LEO constellation.
The configuration file contains a mapping between ground cells and Amarisoft eNB/gNBs with an NTN configuration, along with the definition of a satellite constellation.
ltesat will configure in realtime the eNB/gNBs to select the serving satellites for its NTN cells, in order to allow a continuous coverage in time.
ltesat offers the same comprehensive logging mechanism as other Amarisoft products and smoothly interfaces with Amarisoft GUI.
2 Requirements
2.1 Hardware requirements
-
ltesatis not a performance-intensive executable and can run on any machine.
2.2 Software requirements
- A 64 bit Linux distribution. Fedora 42 is the officially supported distribution.
The following distributions are known as compatible:- Fedora 22 to 42
- Cent OS 7
- Ubuntu 14 to 24
Your system requires at least GLIBC 2.17.
3 Installation
ltesat can be run directly from the directory where it was unpacked.
3.1 Linux setup
ltesat does not need external packages.
3.2 Licensing
ltesat needs a valid Amarisoft license with the NTN option to run.
3.3 Initial testing
- To display the satellite groundtrack:
./ltesat sat-groundtrack.cfg
- To act as a mission control:
./ltesat -m sat-mc.cfg
In mission control mode, the
ltesatruns until it receives aCtrl+Ctermination command.
4 Configuration reference
4.1 Configuration file syntax
The main configuration file uses a syntax very similar to the Javascript Object Notation (JSON) with few extensions.
- Supported types:
- - Numbers (64 bit floating point). Notation:
13.4 - - Complex numbers. Notation:
1.2+3*I - - Strings. Notation:
"string" - - Booleans. Notation:
trueorfalse. - - Objects. Notation:
{ field1: value1, field2: value2, .... } - - Arrays. Notation:
[ value1, value2, .... ]
- - Numbers (64 bit floating point). Notation:
- The basic operations
+,-,*and/are supported with numbers and complex numbers.+also concatenates strings. The operators!,||,&&,==,!=,<,<=,>=,>are supported too. - The numbers
0and1are accepted as synonyms for the boolean valuesfalseandtrue. - {} at top level are optional.
- " for property names are optional, unless the name starts with a number.
- Properties can be duplicated.
If properties are duplicated, they will be merged following JSON merge rules with overriding occuring in reading direction (last overrides previous).
Ex:{ value: "foo", value: "bar", sub: { value: "foo" }, sub: { value: "bar" } }Will be equivalent to:
{ value: "bar", sub: { value: "bar" } } - Files can be included using include keyword (must not be quoted) followed by a string (without :) representing the file to include (path is relative to current file) and terminating by a comma.
Arrays can’t be included.
Merge will be done as for duplicate properties.
If file1.cfg is:value: "foo", include "file2.cfg", foo: "foo"And file2.cfg is:
value: "bar", foo: "bar"Final config will be:
{ value: "bar", foo: "foo" } - A C like preprocessor is supported. The following preprocessor commands are available:
#define var exprDefine a new variable with value expr. expr must be a valid JSON expression. Note that unlike the standard C preprocessor, expr is evaluated by the preprocessor.
#undef varUndefine the variable var.
#include exprInclude the file whose filename is the evaluation of the string expression expr.
#if exprConsider the following text if expr is true.
#elseAlternative of
#ifblock.#elifComposition of
#elseand#if.#endifEnd of
#ifblock.#ifdef varShortcut for
#if defined(var)#ifndef varShortcut for
#if !defined(var)
In the JSON source, every occurrence of a defined preprocessor variable is replaced by its value.
- Backquote strings: JSON expression can be inserted in backquote delimited strings with the
${expr}syntax. Example:`abc${1+2}d`is evaluated as the string"abc3d". Preprocessor variables can be used inside the expression. Backquote strings may span several lines.
4.1.1 JSON merge rules
Merge overriding direction depends on context, i.e source may override destination or the opposite.
JSON merge is recursive for Objects and Arrays.
Example, merging
{
foo: { value: "bar" },
same: "one",
one: 1
}
with
{
foo: { value: "none", second: true },
same: "two",
two: 1
}
Will become:
{
foo: { value: "bar", second: true },
same: "one",
one: 1
two: 1
}
assuming first object overrides second one.
In case of Array merging, the final array length will be the maximum length of all merged arrays.
For each element of the final array, merge will be done considering defined elements only.
Ex:
{
array: [0, 1, 2, { foo: "bar" } ],
array: [3, 4],
array: [5, 6, 7, { bar: "foo" }, 8 ]
}
Will be merged to:
{
array: [5, 6, 7, { foo: "bar", bar: "foo" }, 8 ],
}
4.2 Global properties
constellation_listOptional array of constellation objects. If absent, a single satellite descriptor object is parsed.See single_sat. Each constellation object can either be:
- A shell of circular orbit planes described by the following parameters:
n_planesInteger (range 1 to 72). Number of orbital planes. The orbital planes are spread evenly in longitude of ascending node.
n_sats_per_planeInteger (range 1 to 72). Number of satellites per orbital plane. The satellites are spread evenly in a given plane. The total number of satellites in the shell is given by
n_planes * n_stats_per_plane.inclinationFloat (range 0.0 to 180.0). Inclination in degrees of the orbital planes.
altitudeFloat (range 200e3 to 3700e3). Altitude in meters of the shell.
- An array of single satellite descriptor objects.See single_sat
- A combined TLE file containing several TLE, described by the following parameter:
multiple_tle_filename.String. Filename where the TLEs are stored. The TLEs should be stored in sequence, blank lines are ignored.
- A shell of circular orbit planes described by the following parameters:
output_modeOptional enumeration: az_el, groundtrack, ecef, pass (default = az_el). Selects the wanted output when operating in ’toolbox’ mode:
az_eloutput_mode.az_elDisplays distance, azimuth, elevation and doppler. Needs at a least a valid ground cell definition. See single_cell
groundtrackoutput_mode.groundtrackDisplays latitude, longitude and altitude.
ecefoutput_mode.ecefDisplays ECEF state vectors for position (X, Y, Z) and velocity (VX, VY, VZ).
passoutput_mode.passDisplays next pass information. Needs at least a valid ground cell definition. See single_cell
output_listOptional boolean (default = false). When true, the output will consist of a single point in time, defined by
start_timefor each of the satellites.
When false, the output is a trajectory for a given satellite (as given bysat_id) across time (as given bystart_time,step_msandn_steps).sat_idOptional integer (default = 0). When multiple satellites are defined, and if
output_listis false, selects the satellite of interest.step_msOptional integer (range 10 to 600000, default 1000). Step duration in milliseconds for the satellite trajectory.
n_stepsOptional integer (range 1 to 1440, default 300). Number of steps for the satellite trajectory. For the
passoutput mode, it is the consecutive number of passes to compute.start_timeOptional string, formatted "YYYY-MM-DDTHH:MM:SS[.mmm]" (ISO 8601 format) in UTC time. Defines the starting point for the satellite trajectory or pass estimation. If absent, the current time at execution is taken.
min_elevationOptional integer (range 0 to 80, default 10). Used only in mission control mode or
passoutput mode. Minimum elevation, in degrees, to consider for a valid overhead pass.cells_listOptional array of objects. Each object is a single ground cell descriptor object.See single_cell
If absent, a single ground cell descriptor object is parsed directly.export_typeOptional enumeration: none, json, tle (default = none). Exports the satellites information, timestamped at
export_timein the file specified byexport_filename.
If set tojson, it will export a JSON array of single satellite descriptor objects in theephemerisformat, compatible withltesator Amarisoft LTE gNB/eNB input.
If set totle, it will export the generated TLEs of the satellites, compatible with themultiple_tle_filenameinput ofltesator any other third party software using TLEs.export_filenameOptional string. Mandatory if
export_typeis notnone, ignored otherwise.
Filename where the exported data is written.export_timeOptional string, formatted "YYYY-MM-DDTHH:MM:SS[.mmm]" (ISO 8601 format) in UTC time. Ignored if
export_typeisnone. Epoch to use when generating the exported data. If absent, the current time at execution is taken.
4.3 Single satellite descriptor object
This object is placed either as an element of a constellation object of array type (See constellation)
or at the top level of the configuration file (for a single satellite configuration).
Its configuration is compatible with the ntn object in Amarisoft eNB/gNB configurations.
It contains the following parameters:
tle_filenameOptional string to configure satellite ephemeris from a Two Line Elements (TLE) file.
The file shall contain only the two lines of data and optionally a title line.
When the parameter is present,ephemerisis ignored.default_ephemerisOptional enumeration:
geo,meo,leo. Default isgeo.
Ifephemerisis absent, a default satellite ephemeris is generated so that the satellite is overhead the eNB ground position at the time specified bystart_time. The GEO and MEO satellite will be placed on the equatorial plane (zero inclination) at the longitude of the eNB ground position.
The LEO satellite will be initially placed at the zenith of the eNB position.default_altitudeOptional float, range 200e3 to 36000e3. If
default_ephemerisis used and set tomeoorleo, this parameter (in meters) allows to override the altitude of the chosen orbit.
The parameter is ignored otherwise. The default values are 550e3 forleoand 8063e3 formeo.default_elevation_offsetOptional float, range -90 to 90, default = 0. If
default_ephemerisis used and set toleo, this parameter (in degrees) allows to adjust the initial elevation of the satellite compared to the zenith position.
The parameter is ignored otherwise. Negative values will place the satellite before its zenith pass and positive values after the zenith.ephemerisOptional object to configure satellite ephemeris in the form of orbital parameters.
The ephemeris configuration is understood in a fixed ECI reference frame aligned with the J2000 vernal equinox, like a TLE configuration. If absent and iftle_filenameandsv_filenameare also absent, a default ephemeris is generated.
Contains the following parameters:eccentricityephemeris.eccentricityFloat value. Range 0 to 0.99. Eccentricity, unitless
inclinationephemeris.inclinationFloat value. Range 0 to \pi. Inclination, in radians.
semi_major_axisephemeris.semi_major_axisFloat value. Semi-major axis, in meters.
longitudeephemeris.longitudeFloat value. Range 0 to 2\pi. Longitude of the ascending node, in radians.
periapsisephemeris.periapsisFloat value. Range 0 to 2\pi. Argument of periapsis, in radians.
anomalyephemeris.anomalyFloat value. Range 0 to 2\pi. Mean anomaly of the satellite on its orbit at
epoch, in radians.epochephemeris.epochString, formatted "YYYY-MM-DDTHH:MM:SS[.mmm]" (ISO 8601 format) in UTC time. Epoch for the given orbital parameters.
4.4 Single ground cell descriptor object
This object describes a ground position used as reference for az_el and pass output. For the mission control mode, it describes a ground footprint of the satellite beams.
It contains the following parameters:
ground_positionObject describing the cell center, contains the following parameters:
latitudeground_position.latitudeFloat value. Range -90 to 90. Degrees of latitude.
longitudeground_position.longitudeFloat value. Range -180 to 180. Degrees of longitude.
altitudeground_position.altitudeOptional float value (default = 0). Range -1000m to 20km. Altitude in meters.
radiusOptional float (range 1e3 to 15000e3, default 400e3, used only in mission control mode) Radius of the cell in meters.
supported_constellationsOptional array of integer (used only in mission control mode). Allows to restrict only the satellites of the given constellation indices of the
constellation_listarray to cover the cell. See constellation
4.5 Mission control specific parameters
These parameters are used only when the program is launched with the -m option.
They are also placed at the top level of the configuration file.
ran_node_listArray of objects to describe the connection to Amarisoft eNB/gNB and the mapping between RAN cells and ground cells. Each object contains the following parameters:
addrran_node_list.addrString. IP adress and port of the COM port of the eNB/gNB.
labelran_node_list.labelOptional string. Custom label for this eNB used in logs and console output.
mapping_listran_node_list.mapping_listArray of objects. Describes the mapping between a ground cell and one or more RAN cells. Each ground cell can only be referenced in one RAN node and each RAN cell can only be mapped to one ground cell. Each object contains the following parameters:
ground_cell_idran_node_list.mapping_list.ground_cell_idInteger. Index of the ground cell in the
cell_listarrayran_cell_listran_node_list.mapping_list.ran_cell_listArray of integers.
cell_idvalues of the RAN cells mapped to this ground cell. With more than 1 cells, the mission control will ensure a small overlap between satellite pass to offer a continuous coverage of the cell and the possibilities for the UEs to perform handovers.
pass_overlapOptional integer (range 10 to 120, default 30). Overlap duration in seconds of the coverage of the ground cells with more than one RAN cell.
dump_ran_statusOptional boolean. Print useful information in the console output. This options is preferred when no GUI is connected to the
ltesattool.log_filenameString. Set the log filename. If no leading
/, it is relative to the configuration file path.log_optionsString. Set the logging options as a comma separated list of assignments.
- layer.level=verbosity. For each layer, the log verbosity can be set
to
none,error,infoordebug. In debug level, the content of the transmitted data is logged. - layer.max_size=n. When dumping data content, at
most
nbytes are shown in hexa. For ASN.1, NAS or Diameter content, show the full content of the message ifn > 0. - time=[sec|short|full]. Display the time as seconds, time only or full date and time (default = time only).
- time.us=[0|1]. Dump time with microseconds precision.
- file=cut. Close current file log and open a new one.
- file.rotate=now. Rename current log with timestamp and open new one.
- file.rotate=size. Rename current log every time it reaches size bytes open new one. Size is an integer and can be followed by K, M or G.
- file.path=path. When log rotation is enabled, move current log to this path instead of initial log path.
- append=[0|1]. (default=0). If 0, truncate the log file when opening it. Otherwise, append to it.
Available layers are: PROD
- layer.level=verbosity. For each layer, the log verbosity can be set
to
log_syncOptional boolean (default = false). If true, logs will be synchronously dumped to file.
Warning, this may lead to performances decrease.com_addrString. IP adress and port on which the
ltesatsoftware can receive websocket connection
5 Examples
5.1 Toolbox usage
Fetch a well-known TLE from online source in a file, e.g. here is the ISS(ZARYA) TLE from 2024/03/07, stored in iss.tle:
1 25544U 98067A 24067.37790297 .00014521 00000-0 26457-3 0 9993 2 25544 51.6412 99.9639 0005680 335.2557 148.0116 15.49704815442763 |
5.1.1 Overhead pass
Here is the configuration file to get the next 10 overhead passes over Paris, with a minimum elevation of 20°, from the 2024/03/10 onward, stored in sat-pass.cfg:
/* ltesat configuration file version ##VERSION##
* Copyright (C) 2024-2025 Amarisoft
*/
{
output_mode: "pass",
min_elevation: 20,
n_steps: 10,
start_time: "2024-03-10T00:00:00",
ground_position: {
latitude: 48.8538,
longitude: 2.3475
},
tle_filename: "iss.tle"
}
|
It will give the following output:
[user@host]$ ./ltesat sat-pass.cfg
Satellite utility version 2024-03-15, Copyright (C) 2012-2025 Amarisoft
[OK] TLE at epoch 2024-03-07T09:04:11.000
T_start(UTC) T_max(UTC) Elevation(d) T_end(UTC)
2024-03-10T00:20:18.740 00:22:27.640 50.276 00:24:36.540
2024-03-10T01:57:11.100 01:59:26.580 81.349 02:01:42.060
2024-03-10T21:55:07.940 21:57:20.320 65.740 21:59:32.710
2024-03-10T23:32:01.760 23:34:11.600 52.915 23:36:21.450
2024-03-11T01:08:59.030 01:11:12.550 65.108 01:13:26.080
2024-03-11T02:45:58.970 02:47:52.220 37.528 02:49:45.480
2024-03-11T21:07:09.920 21:09:10.410 44.918 21:11:10.910
2024-03-11T22:43:42.410 22:45:54.320 59.901 22:48:06.240
2024-03-12T00:20:44.720 00:22:55.620 55.556 00:25:06.530
2024-03-12T01:57:35.880 01:59:43.090 55.364 02:01:50.310
5.1.2 Trajectory
Here is the configuration file to get the detailed trajectory for one of those pass, with one point every 10 seconds over 5 minutes, stored in sat-traj.cfg:
/* ltesat configuration file version ##VERSION##
* Copyright (C) 2024-2025 Amarisoft
*/
{
output_mode: "az_el",
n_steps: 30,
step_ms: 10000,
start_time: "2024-03-10T01:57:00",
ground_position: {
latitude: 48.8538,
longitude: 2.3475
},
tle_filename: "iss.tle"
}
|
It will give the following output:
[user@host]$ ./ltesat sat-traj.cfg
Satellite utility version 2024-03-15, Copyright (C) 2012-2025 Amarisoft
[OK] TLE at epoch 2024-03-07T09:04:11.000
Time(UTC) Distance(km) Azimuth(d) Elevation(d) Doppler(ppm)
2024-03-10T01:57:00.000 1126.994 291.677 17.929 21.805
2024-03-10T01:57:10.000 1061.955 291.937 19.706 21.571
2024-03-10T01:57:20.000 997.688 292.233 21.673 21.288
2024-03-10T01:57:30.000 934.361 292.574 23.865 20.942
2024-03-10T01:57:40.000 872.186 292.971 26.328 20.516
2024-03-10T01:57:50.000 811.436 293.444 29.115 19.987
2024-03-10T01:58:00.000 752.465 294.017 32.295 19.324
2024-03-10T01:58:10.000 695.733 294.731 35.949 18.486
2024-03-10T01:58:20.000 641.842 295.646 40.175 17.419
2024-03-10T01:58:30.000 591.574 296.869 45.082 16.055
2024-03-10T01:58:40.000 545.940 298.594 50.778 14.314
2024-03-10T01:58:50.000 506.200 301.214 57.346 12.110
2024-03-10T01:59:00.000 473.844 305.672 64.770 9.381
2024-03-10T01:59:10.000 450.471 314.804 72.789 6.126
2024-03-10T01:59:20.000 437.526 340.282 80.217 2.454
2024-03-10T01:59:30.000 435.940 44.006 81.573 -1.404
2024-03-10T01:59:40.000 445.835 79.137 74.933 -5.155
2024-03-10T01:59:50.000 466.479 90.735 66.872 -8.541
2024-03-10T02:00:00.000 496.533 96.016 59.239 -11.418
2024-03-10T02:00:10.000 534.407 98.996 52.428 -13.761
2024-03-10T02:00:20.000 578.563 100.908 46.498 -15.621
2024-03-10T02:00:30.000 627.674 102.240 41.385 -17.080
2024-03-10T02:00:40.000 680.662 103.224 36.984 -18.220
2024-03-10T02:00:50.000 736.686 103.983 33.183 -19.115
2024-03-10T02:01:00.000 795.098 104.588 29.882 -19.822
2024-03-10T02:01:10.000 855.404 105.083 26.994 -20.385
2024-03-10T02:01:20.000 917.223 105.498 24.448 -20.837
2024-03-10T02:01:30.000 980.263 105.851 22.186 -21.203
2024-03-10T02:01:40.000 1044.297 106.156 20.162 -21.502
2024-03-10T02:01:50.000 1109.145 106.423 18.336 -21.748
5.1.3 Export
For testing purpose, it could be useful to generate a ’virtual TLE’ that simulates a satellite passing overhead a given location at a given time.
Here is an example with the default_ephemeris and export_type parameter, stored in sat-export.cfg:
/* ltesat configuration file version ##VERSION##
* Copyright (C) 2024-2025 Amarisoft
*/
{
output_mode: "az_el",
n_steps: 10,
step_ms: 30000,
start_time: "2024-03-15T14:30:00",
ground_position: {
latitude: 48.8538,
longitude: 2.3475
},
default_ephemeris: "leo",
default_altitude: 700e3,
default_elevation_offset: -60,
export_type: "tle",
export_time: "2024-03-15T00:00:00.000",
export_filename: "pass_14h30.tle"
}
|
And the resulting TLE pass_14h30.tle:
1 99999U 24999A 24075.00000000 -.00000000 00000-0 00000-0 0 11 2 99999 48.8538 305.9746 0 357.5651 150.3878 14.57888518000073 |
5.2 Mission control
Mission control file are too long to be included as is in this documentation, but a sample file is given in sat-mc.cfg