LTEMBMSGW is a LTE MBMS Gateway. It can easily be used with the Amarisoft LTE eNodeB to build an LTE MBMS test system.
Your system requires at least GLIBC 2.17.
We assume that the Fedora distribution is running and that the network access thru the Gigabit Ethernet port is correctly configured.
LTEMBMSGW can be run directly from the directory when it was unpacked. No need for explicit installation.
LTEMBMSGW uses the SCTP protocol for which the necessary packages are not usually installed. In order to install them, do as root user:
dnf install lksctp-tools kernel-modules-extra
sudo apt-get install lksctp-tools linux-image-extra-3.13.0-24-generic
Note that linux-image-extra package name may differ depending on your kernel version.
To verify that SCTP kernel module is running, do as root user:
checksctp
If it reports that the protocol is not supported,
Then reboot the PC in case the Linux kernel was upgraded too.
LTEMBMSGW has been compiled against openssl version 1.1.1w.
If your system does not have compatible version installed you may have this error message at startup:
error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory
To overcome this problem, you may:
libs subdirectory of your release tarball.In case of persisting issue, raise a ticket from our support site at https://support.amarisoft.com/ with the information provided by below commands executed in LTEMBMSGW directory:
uname -a ls -l ldd ./ltembmsgw openssl version
LTEMBMSGW needs a LTEMME license key to run.
Please refer to the ltemme documentation.
./lteenb config/enb-mbms.cfg
./ltembmsgw config/mbmsgw.cfg
mbms command in the eNodeB monitor. You should see a non zero bitrate for each service and zero packet error.
When this basic test work, you can customize the eNodeB and MBMS Gateway configuration to use your own generated multicast services.
The main configuration file uses a syntax very similar to the Javascript Object Notation (JSON) with an extension to support complex numbers and a few mathematical operations. The supported types are:
13.4
1.2+3*I
"string"
true or false.
{ field1: value1, field2: value2, .... }
[ value1, value2, .... ]
The basic operations +, -, * and / are
supported with numbers and complex numbers.
The numbers 0 and 1 are accepted as synonyms for the
boolean values false and true.
log_filenameString. Set the log filename. If no leading /, it is relative to the
configuration file path. See Log file format.
log_optionsString. Set the logging options as a comma separated list of assignments.
none, error, info or debug. In debug
level, the content of the transmitted data is logged.
n bytes are shown in hexa. For ASN.1, NAS or Diameter content, show the full content of the message if n > 0.
Available layers are: gtpu, m2ap
log_syncOptional boolean (default = false). If true, logs will be synchronously dumped to file.
Warning, this may lead to performances decrease.
com_addrOptional string. Address of the WebSocket server remote API. See Remote API.
If set, the WebSocket server for remote API will be enabled and bound to this address.
Default port is 9004.
Setting IP address to [::] will make remote API reachable through all network interfaces.
com_nameOptional string. Sets server name. MBMSGW by default
com_ssl_certificateOptional string. If set, forces SSL for WebSockets. Defines CA certificate filename.
com_ssl_keyOptional string. Mandatory if com_ssl_certificate is set. Defines CA private key filename.
com_ssl_peer_verifyOptional boolean (default is false). If true, server will check client certificate.
com_ssl_caOptional string. Set CA certificate. In case of peer verification with self signed certificate, you should use the client certificate.
com_log_lockOptional boolean (default is false). If true, logs configuration can’t be changed
via config_set remote API.
com_log_usOptional boolean (default is false). If true, logs sent by log_get remote API
response will have a timestamp_us parameters instead of timestamp
com_authOptional object. If set, remote API access will require authentication.
Authentication mechanism is describe in Remote API Startup section.
passfileOptional string. Defines filename where password is stored (plaintext).
If not set, password must be set
passwordOptional string. Defines password.
If not set, passfile must be set.
unsecureOptional boolean (default false). If set, allow password to be sent plaintext.
NB: you should set it to true if you access it from a Web Browser (Ex: Amarisoft GUI)
without SSL (https) as your Web Browser may prevent secure access to work.
com_log_countOptional number (Default = 8192). Defines number of logs to keep in memory before dropping them.
Must be between 4096 and 2097152).
sim_eventsArray of object. Each element gives an event configuration to execute for
this UE.
Event configuration is exactly the same as for Remote API messages
except that message field must be event.
sim_events_loop_countIf set, will define loop_count for each event of sim_events, See loop_count.
sim_events_loop_delayIf set, will define loop_delay for each event of sim_events, See loop_delay.
license_serverConfiguration of the Amarisoft license server to use.
Object with following properties:
server_addrString. IP address of the license server.
nameOptional string. Text to be displayed inside server monitor or remote API.
tagOptional string. If set, server will only allow license with same tag.
Example:
license_server: {
server_addr: "192.168.0.20",
name: "My license"
}
gtp_bind_addrString. Set source IP address (and an optional port) of the GTP-U
packets. The default value is "0.0.0.0:2152".
Syntax:
m2ap_bind_addrOptional string. IP address and optional port on which the M2AP SCTP connection is bound. The default port is 36443.
mce_idInteger. Range: 0 to 65535. Global MCE Identifier used in M2 signaling.
enb_time_offsetOptional integer (default = 0). Offset in ms applied to the MBMSGW
International Atomic Time (TAI) so as to generate a time that should
match the eNB RF time. The current value can be retrieved by
typing the time monitor command in eNB or MBMSGW prompt. This
is used to synchronize the two components so as to have meaningful
timestamps in the SYNC packets (indicating the start of the MCH
Scheduling Periods).
Note: the MBMSGW derives the TAI from the UTC OS clock and the
right/UTC OS time zone.
time_offsetInteger. Default time offset in ms added to all the SYNC
timestamps. Can be overridden by the time_offset property of
each service. It is recommended to set it to at least 2 MCH Scheduling
Period to avoid having the eNB dropping SYNC packets due to a timestamp
equal to the current MCH Scheduling Period.
Note: the MBMS Gateway uses the system real time clock as clock source. If synchronous transmission is needed, it should be synchronized to the eNodeB RF time.
servicesArray of objects. Contain the definition of each service.
Property of each service:
tmgiObject. Service identifier (only used for error reporting). Contain the following fields:
plmnString (5 or 6 digits). PLMN identity of the service.
service_idInteger. 24 bit service identity.
service_area_idInteger. Range: 0 to 65535. MBMS service area identifier for this service.
session_idOptional integer. Range: 0 to 255. MBMS session identifier for this service.
gtp_addrString. IP address (and optional port) to which the GTP packets are sent. It is normally a multicast address. Several services can share the same IP address if they have a different TEID.
gtp_teid32 bit integer. GTP TEID on which the GTP packets are sent.
autostartOptional boolean (default = true). Indicates if service is automatically started when the eNB connects to the MBMS Gateway or if it should be manually launched with the service_start command.
scheduling_periodRange: from 4 to 1024. Must be a power of two. Duration of the scheduling period in 10 ms units. Must match the corresponding MCH scheduling period configured in the eNodeB.
time_offsetOptional integer. Time offset in ms added to the SYNC timestamps. If not provided, the default time offset is used.
forward_modeOptional boolean (default = false). If set, gateway won’t add sync headers and only forward packet to the eNB.
tosOptional integer (default = 0). IPv4 header TOS field (6 bits DSCP + 2 bits ECN).
traffic_classOptional integer (default = 0). IPv6 header traffic class field (6 bits DSCP + 2 bits ECN).
ttlOptional integer (default = 64). IP header TTL field.
componentsArray of object. A service contains several components. Each component is the data coming from a given IP address (usually multicast).
Component properties:
ip_addrString. Destination IPv4/v6 address and port for the component.
if_addrOptional string (default = "0.0.0.0"). IP address of
the network interface for the multicast join.
simOptional boolean (default = false). If true, RTP packets
coming from ip_addr are generated using a RTP payload
of rtp_payload_len bytes and a bitrate of
bitrate.
rtp_payload_lenOptional integer. Only meaningful if sim = true. RTP payload length in bytes (default = 1460).
bitrateOptional integer. Only meaningful if sim = true. Bitrate in bit/s of the generated RTP stream. The bitrate includes the size of the IP, UDP and RTP headers.
area_info_listArray of object. Each object defines the parameters of one MBSFN area:
area_idRange: 0 to 255. Area identifier.
non_mbsfn_region_lengthEnumeration: 1, 2. Number of CCH symbols. For 1.4 MHz downlink, only
2 is allowed.
mcch_configObject. MCCH configuration:
mcch_repetition_periodRange: 32 to 256, power of two. MCCH repetition period (in 10 ms frames).
mcch_offsetRange: 0 to 10. MCCH offset.
mcch_modification_periodEnumeration: 512, 1024. (in 10 ms frames).
mcch_sf_allocBit string. Length = 6 (1 frame). In FDD, the bits correspond to subframes 1, 2, 3, 6, 7, 8. In TDD, the bits correspond to subframes 3, 4, 7, 8, 9.
signalling_mcsEnumeration: 2, 7, 13, 19. MCS for MCCH and MCHSI transmission. MCCH and MCHSI are critical to decode the MBMS data (MTCH), so their MCS should be lower than the one of the data.
mbsfn_area_configurationObject. MBSFN area configuration. Most of the content of this object is transmitted in the MCCH.
common_sf_allocArray of object. Defines the subframes dedicated to this MBSFN area. Each object has the following fields:
radio_frame_allocation_periodRange: 1 to 32, power of two. Allocation period (in 10 ms frames).
radio_frame_allocation_offsetRange: 0 to 7. offset in the allocation period (in 10 ms frames).
subframe_allocationBit string. Length = 6 (1 frame) or 24 (4 frames). In FDD, the bits correspond to subframes 1, 2, 3, 6, 7, 8. In TDD, the bits correspond to subframes 3, 4, 7, 8, 9.
common_sf_alloc_periodRange: 4 to 256, power of two. Common subframe allocation period (in 10 ms frames). The PMCH are allocated consecutively during this period.
pmch_info_listArray of objects. List of PMCH. Each PMCH has the following properties:
pmch_configObject. PMCH physical parameters.
sf_alloc_countInteger >= 1. Number of subframes allocated to this PMCH per common period.
data_mcsRange: 0 to 28. MCS used for the MBMS data (MTCH).
data_mcs2Optional integer. Range: 0 to 27. If provided, data_mcs
is ignored and an alternate MCS table is used to allow 256QAM
MBMS. Note: 256QAM MBMS is an optional release 12 feature,
so not all UEs can receive a PMCH using data_mcs2.
mch_scheduling_periodRange: 4 to 1024, power of two. Scheduling period (in 10 ms frames) for the MCH. MCHSI is transmitted with this periodicity. Must be >= common_sf_alloc_period. For the first PMCH, must be <= mcch_repetition_period. Note: only release 12 UEs support the value 4, so the effective range to support all UEs is 8 to 1024.
mbms_session_info_listArray of objects. List of sessions in this PMCH. Each session has the following properties:
tmgiObject. Temporary Mobile Group Identity.
plmnString (5 or 6 digits). PLMN identity.
service_id24 bit integer. Service identity.
logical_channel_identityRange: 0 to 28. MAC logical channel identity. Must be different for each session in the PMCH. 0 is reserved for the MCCH in the first PMCH.
You can access LTEMBMSGW via a remote API.
Protocol used is WebSocket as defined in RFC 6455
(https://tools.ietf.org/html/rfc6455).
Note that Origin header is mandatory for the server to accept connections.
This behavior is determined by the use of nopoll library.
Any value will be accepted.
Messages exchanged between client and LTEMBMSGW server are in strict JSON
format.
Each message is represented by an object. Multiple message can be sent to
server using an array of message objects.
Time and delay values are floating number in seconds.
There are 3 types of messages:
Message sent by client.
Common definition:
messageString. Represent type of message. This parameter is mandatory and depending
on its value, other parameters will apply.
message_idOptional any type. If set, response sent by the server to this message will have same message_id. This is used to identify response as WebSocket does not provide such a concept.
start_timeOptional float. Represent the delay before executing the message.
If not set, the message is executed when received.
absolute_timeOptional boolean (default = false). If set, start_time is interpreted as absolute.
You can get current clock of system using time member of any response.
standaloneOptional boolean (default = false). If set, message will survive WebSocket disconnection, else, if socket is disconnected before end of processing, the message will be cancelled.
loop_countOptional integer (default = 0, max = 1000000). If set, message will be repeated loop_count time(s)
after loop_delay (From message beginning of event).
Response will have a loop_index to indicate iteration number.
loop_delayOptional number (min = 0.1, max = 86400). Delay in seconds to repeat message from its start_time.
Mandatory when loop_count is set > 0.
Message sent by server after any request message as been processed.
Common definition:
messageString. Same as request.
message_idOptional any type. Same as in request.
timeNumber representing time in seconds since start of the process.
Usefull to send command with absolute time.
utcNumber representing UTC seconds.
Message sent by server on its own initiative.
Common definition:
messageString. Event name.
timeNumber representing time in seconds.
Usefull to send command with absolute time.
When WebSocket connections is setup, LTEMBMSGW will send a first message with
name set to com_name and type set to MBMSGW.
If authentication is not set, message will be ready:
{
"message": "ready",
"type": "MBMSGW",
"name": <com_name>,
"version": <software version>,
"product": <Amarisoft product name (optional)>
}
If authentication is set, message will be authenticate :
{
"message": "authenticate",
"type": "MBMSGW",
"name": <com_name>,
"challenge": <random challenge>
}
To authenticate, the client must answer with a authenticate message
and a res parameter where:
res = HMAC-SHA256( "<type>:<password>:<name>", "<challenge>" )
res is a string and HMAC-SHA256 refers to the standard algorithm
(https://en.wikipedia.org/wiki/HMAC)
If the authentication succeeds, the response will have a ready field
set to true.
{
"message": "authenticate",
"message_id": <message id>,
"ready": true
}
If authentication fails, the response will have an error field and will
provide a new challenge.
{
"message": "authenticate",
"message_id": <message id>,
"error": <error message>,
"type": "MBMSGW",
"name: <name>,
"challenge": <new random challenge>
}
If any other message is sent before authentication succeeds,
the error "Authentication not done" will be sent as a response.
If a message produces an error, response will have an error string field representing the error.
You will find in this documentation a sample program: ws.js.
It is located in doc subdirectory.
This is a nodejs program that allow to send message to LTEMBMSGW.
It requires nodejs to be installed:
dnf install nodejs npm npm install nodejs-websocket
Use relevant package manager instead of NPM depending on your Linux distribution.
Then simply start it with server name and message you want to send:
./ws.js 127.0.0.1:9004 '{"message": "config_get"}'
config_getRetrieve current config.
Response definition:
typeAlways "MBMSGW"
nameString representing server name.
logsObject representing log configuration.
With following elements:
layersObject. Each member of the object represent a log layer configuration:
layer nameObject. The member name represent log layer name and parameters are:
levelSee log_options
max_sizeSee log_options
keySee log_options
cryptoSee log_options
payloadSee log_options
countNumber. Number of bufferizer logs.
rotateOptional number. Max log file size before rotation.
pathOptional string. Log rotation path.
bcchBoolean. True if BCCH dump is enabled (eNB only).
mibBoolean. True if MIB dump is enabled (eNB only).
lockedOptional boolean. If true, logs configuration can’t be changed
with config_set API.
config_setChange current config.
Each member is optional.
Message definition:
logsOptional object. Represent logs configuration. Same structure as config_get (See config_get logs member).
All elements are optional.
Layer name can be set to all to set same configuration for all layers.
If set and logs are locked, response will have logs property set to locked.
log_getGet logs.
This API has a per connection behavior. This means that the response will depend on previous calls
to this API within the same WebSocket connection.
In practice, logs that have been provided in a response won’t be part of subsequent request unless
connection is reestablished. To keep on receiving logs, client should send a new log_get request
as soon as the previous response has been received.
If a request is sent before previous request has been replied, previous request will be replied right now
without considering specific min/max/timeout conditions.
Message definition:
minOptional number (default = 1). Minimum amount of logs to retrieve.
Response won’t be sent until this limit is reached (Unless timeout occurs).
maxOptional number (default = 4096). Maximum logs sent in a response.
timeoutOptional number (default = 1). If at least 1 log is available and no more logs have been generated for this time, response will be sent.
allow_emptyOptional boolean (default = false). If set, response will be sent after timeout, event if no logs are available.
rntiOptional number. If set, send only logs matching rnti.
ue_idOptional number. If set, send only logs with matching ue_id.
layersOptional Object. Each member name represents a log layer and values must be
string representing maximum level. See log_options.
If layers is not set, all layers level will be set to debug,
else it will be set to none.
Note also the logs is also limited by general log level. See log_options.
shortOptional boolean (default = false). If set, only first line of logs will be dumped.
headersOptional boolean. If set, send log file headers.
start_timestampOptional number. Is set, filter logs older than this value in milliseconds.
end_timestampOptional number. Is set, filter logs more recent than this value in milliseconds.
max_sizeOptional number (default = 1048576, i.e. 1MB). Maximum size in bytes of the generated JSON message. If the response exceeds this size, the sending of logs will be forced independently from other parameters.
Response definition:
logsArray. List of logs. Each item is a an object with following members:
dataArray. Each item is a string representing a line of log.
timestampNumber. Milliseconds since January 1st 1970. Not present if com_log_us is set in configuration.
timestamp_usNumber. Microseconds since January 1st 1970. Only present if com_log_us is set in configuration.
layerString. Log layer.
levelString. Log level: error, warn, info or debug.
dirOptional string. Log direction: UL, DL, FROM or TO.
ue_idOptional number. UE_ID.
cellOptional number (only for PHY layer logs). Cell ID.
rntiOptional number (only for PHY layer logs). RNTI.
frameOptional number (only for PHY layer logs). Frame number (Subframe is decimal part).
channelOptional string (only for PHY layer logs). Channel name.
srcString. Server name.
idxInteger. Log index.
headersOptional array. Array of strings.
discontinuityOptional number. If set, this means some logs have been discarded due to log buffer overflow.
microsecondsOptional boolean. Present and set to true if com_log_us is set in configuration file.
log_setAdd log.
Message definition:
logOptional string. Log message to add. If set, layer and level are mandatory.
layerString. Layer name. Only mandatory if log is set.
levelString. Log level: error, warn, info or debug. Only mandatory if log is set.
dirOptional string. Log direction: UL, DL, FROM or TO.
ue_idOptional number. UE_ID.
flushOptional boolean (default = false). If set, flushes fog file.
rotateOptional boolean (default = false). If set, forces log file rotation.
cutOptional boolean (default = false). If set, forces log file reset.
log_resetResets logs buffer.
licenseRetrieves license file information.
quitTerminates ltembmsgw.
helpProvides list of available messages in messages array of strings
and events to register in events array of strings.
statsReport statistics for LTEMBMSGW.
Every time this message is received by server, statistics are reset.
Warning, calling this message from multiple connections simultaneously will modify the
statistics sampling time.
Response definition:
cpuObject. Each member name defines a type and its value cpu load in % of one core.
instance_idNumber. Constant over process lifetime. Changes on process restart.
service_startStart a service.
Message definition:
service_idInteger. Identifier of service to start.
service_stopStop a service.
Message definition:
service_idInteger. Identifier of service to stop.
When a message is dumped, the format is:
time layer - message
When a data PDU is dumped (debug level), the format is:
time layer dir ip_address short_content
long_content
timeTime using the selected format.
layerIndicate the layer ([M2AP] or [GTPU] here).
dirDirection: TO or FROM.
ip_addresssource or destination IP address, depending on the dir field.
short_contentSingle line content.
long_contentlayer.max_size > 0.
layer.max_size > 0.
license remote API
com_logs_lock parameter is renamed to com_log_lock. com_logs_lock is still supported for backward compatibility
com_log_us parameter
loop_count and loop_delay to remote API messages
sim_events, sim_events_loop_count and sim_events_loop_delay
com_ssl_ca parameter for SSL verification
com_logs_lock parameter added to disable logs configuration change via remote API
com_addr parameter now uses [::] address instead of 0.0.0.0 in the delivered configuration file to allow IPv6 connection
utc parameter is added to remote API response messages
m2ap_bind_addr parameter description is added
start_timestamp and end_timestamp are added to log_get API
license monitor command is added
ltembmsgw is copyright (C) 2012-2024 Amarisoft. Its redistribution
without authorization is prohibited.
ltembmsgw is available without any express or implied warranty. In
no event will Amarisoft be held liable for any damages arising from
the use of this software.
For more information on licensing, please refer to license.pdf file.
Multimedia Broadcast Multicast Service
MBMS synchronisation protocol
Temporary Mobile Group Identity