[[osmobts_hardware_support]] == OsmoBTS hardware support OsmoBTS consists of a _common_ part that applies to all BTS models as well as _hardware-specific_ parts for each BTS model. The hardware specific parts are generally referred to as the _bts_model_ code. The common part includes the core BTS architecture as well as code for implementing the external interfaces such as Abis, control, PCU socket and GSMTAP. The bts_model parts include support for driving one particular implementation of a GSM physical layer (PHY). Such a physical layer implementation can come in many forms. Sometimes it runs on a general purpose CPU, sometimes on a dedicated ARM core, a dedicated DSP, a combination of DSP and FPGA. Every PHY implementation offers some kind of primitives by which the PHY can be controlled, and by which the PHY exchanges data with the higher layers of the protocol stack in the OsmoBTS code. The PHY-specific primitives are encapsulated in the bts_model code, and offered as a PHY-independent _L1SAP_ interface towards the common part of OsmoBTS. In addition, each bts_model implements a set of functions that the common part calls. Those functions are pre-fixed by _bts_model__. Each bts_model may offer * model-specific VTY commands for both configuration and run-time interaction * model-specific command line arguments * model-specific control interface commands == `osmo-bts-sysmo` for sysmocom sysmoBTS The sysmocom sysmoBTS is a range of GSM BTSs based around an embedded system implementing the PHY in a combination of DSP+FPGA. The PHY is configured by a set of primitives described by header files. Those primitives are exchanged over a set of message queues exposed on the Linux-running ARM core via device nodes in `/dev/msgq/`. Internally, the message queues map to shared memory between the Linux-running ARM core and the DSP running the PHY implementation. The OsmoBTS bts_model code for the sysmoBTS can be found in the `src/osmo-bts-sysmo` sub-directory of the OsmoBTS code base. `osmo-bts-sysmo` has been the primary target platform for OsmoBTS for many years and is thus the most feature-complete and mature platform supported by OsmoBTS at this point. The sysmoBTS PHY supports a direct PHY interface to OsmoPCU, reducing the latency and amount of primitives that OsmoBTS would otherwise need to pass through from the PHY message queues to the PCU socket and vice-versa. === `osmo-bts-sysmo` specific command line arguments *--dsp-trace 'DSPMASK'*:: Set the DSP trace flags (a single hexadecimal 32bit value). This has been deprecated by VTY based commands, see <> for further information. *--pcu-direct*:: Indicate that an external PCU (e.g. OsmoPCU) will directly open the DSP message queues to the PHY / PH-SAP, and only MPH primitives are passed via OsmoBTS. === `osmo-bts-sysmo` specific VTY commands For a auto-generated complete syntax reference of the VTY commands, please see the associated _OsmoBTS VTY reference manual_ <>. The section below only lists the most important commands. ==== at the 'SHOW' node ===== `show trx 0 clock-source` Display the currently active clock source configuration for the TRX [[osmo-bts-sysmo-dsp-trace]] ===== `show trx 0 dsp-trace-flags` Show the currently active DSP trace flags for the TRX ===== `trx 0 dsp-trace-flag` Use this command to enable/disable/configure the DSP tracing flags that define what debug messages will appear on `/dev/rtfifo/dsp_trace`. ==== at the 'ENABLE' node ===== `trx 0 tx-power <-110-100>` Change the current TRX transmit power to the given value in dBm. ===== `trx 0 rf-clock-info reset` Part of the clock calibration procedure: Reset the clock correction value. ===== `trx 0 rf-clock-info correct` Part of the clock calibration procedure: Apply the current measured correction value between the reference clock and the local clock. ==== at the 'PHY instance' node ==== `clock-calibration eeprom` Obtain clock calibration value from EEPROM. ==== `clock-calibration default` Use hardware default clock calibration value. ==== `clock-calibration <-4095-4095>` Use specified clock calibration value (not EEPROM/default). ==== `clock-source (tcxo|ocxo|ext|gps)` Specify the clock source for the PHY: tcxo:: Use the TCXO. This is the default on sysmoBTS 2050. ocxo:: Use the OCXO (only valid on units equipped with OCXO). This is the default on all sysmoBTS 1002/1020/1100 and SOB-BTS. ext:: Use the external clock input. gps:: Use the clock derived from GPS. You shouldn't use this clock directly, but rather use the TCXO and regularly re-calibrate against GPS. ==== `trx-calibration-path PATH` Use calibration files from the given 'PATH', rather tan calibration values from the EEPROM. === `osmo-bts-sysmo` specific control interface commands ==== trx.0.clock-info Obtain information on the current clock status: ---- bsc_control.py -d localhost -p 4238 -g trx.0.clock-info Got message: GET_REPLY 1 trx.0.clock-info -100,ocxo,0,0,gps ---- which is to be interpreted as: * current clock correction value is -100 ppb * current clock source is OCXO * deviation between clock source and calibration source is 0 ppb * resolution of clock error measurement is 0 ppt (0 means no result yet) * current calibration source is GPS When this attribute is set, any value passed on is discarded, but the clock calibration process is re-started. ==== trx.0.clock-correction This attribute can get and set the current clock correction value: ---- bsc_control.py -d localhost -p 4238 -g trx.0.clock-correction Got message: GET_REPLY 1 trx.0.clock-correction -100 ---- ---- bsc_control.py -d localhost -p 4238 -s trx.0.clock-correction -- -99 Got message: SET_REPLY 1 trx.0.clock-correction success ---- == `osmo-bts-trx` for OsmoTRX OsmoTRX is a C-language implementation of the GSM radio modem, originally developed as the 'Transceiver' part of OpenBTS. This radio modem offers an interface based on top of UDP streams. The OsmoBTS bts_model code for OsmoTRX is called `osmo-bts-trx`. It implements the UDP stream interface of OsmoTRX, so both parts can be used together to implement a complete GSM BTS based on general-purpose computing SDR. As OsmoTRX is general-purpose software running on top of Linux, it is thus not tied to any specific physical hardware. At the time of this writing, OsmoTRX supports a variety of Lime Microsystems and Ettus USRP SDRs via the UHD driver, as well as the Fairwaves UmTRX and derived products. OsmoTRX is not a complete GSM PHY but 'just' the radio modem. This means that all of the Layer 1 functionality such as scheduling, convolutional coding, etc. is actually also implemented inside OsmoBTS. As such, the boundary between OsmoTRX and `osmo-bts-trx` is at a much lower interface, which is an internal interface of other more traditional GSM PHY implementations. Besides OsmoTRX, there are also other implementations (both Free Software and proprietary) that implement the same UDP stream based radio modem interface. === `osmo-bts-trx` specific VTY commands For a auto-generated complete syntax reference of the VTY commands, pleas see the associated _OsmoBTS VTY reference manual_ <>. The section below only lists the most important commands. ==== at the 'SHOW' node ===== `show transceivers` Display information about configured/connected OsmoTRX transceivers in human-readable format to current VTY session. ==== at the 'PHY' configuration node ===== `osmotrx ip HOST` Set the IP address for the OsmoTRX interface for both the local (OsmoBTS) and remote (OsmoTRX) side of the UDP flows. This option has been deprecated by the more detailed option `osmotrx ip (local|remote) A.B.C.D`. ===== `osmotrx ip (local|remote) A.B.C.D` Set the IP address for the OsmoTRX interface for either the local (OsmoBTS) or remote (OsmoTRX) side of the UDP flows. ===== `osmotrx base-port (local|remote) <0-65535>` Configure the base UDP port for the OsmoTRX interface for either the local (OsmoBTS) or remote (OsmoTRX) side of the UDP flows. ===== `osmotrx fn-advance <0-30>` Set the number of frames to be transmitted to transceiver in advance of current GSM frame number. GSM is a TDMA (time division multiple access) system on the radio interface. OsmoTRX is the "clock master" of that in the Osmocom implementation. It informs OsmoBTS of the current GSM frame number. However, as there is non-zero delays (UDP packet transmission delay, operating system scheduler delay on both OsmoTRX and OsmoBTS side, ...), OsmoBTS must compensate for that delay by "advancing" the clock a certain amount of time. In other words, if OsmoTRX informs us that the current frame number is N, we advance it by `fn-advance` and transmit burst data for `N + fn-advance` towards OsmoTRX. The fn-advance should be kept as low as possible to avoid additional delays to the user voice plane as well as to improve the performance of the control plane (LAPDm) as well as GPRS. However, fn-advance must be kept sufficiently high to ensure no underruns on the OsmoTRX side. The detailed value will depend on your underlying computer systems, operating system and related tuning parameters. Running OsmoTRX on a remote host will inevitably require a higher fn-advance than running it on the same machine, where the UDP packets are just passed over the loopback device. The default value for `fn-advance` is 2 (corresponding to 9.2 milliseconds). ===== `osmotrx rts-advance <0-30>` Set the number of frames to be requested from L1SAP in advance of current frame number and fn-advance. The value specified as `rts-advance` is added to the current GSM frame number as reported by OsmoTRX *and* the `osmotrx fn-advance` in order to generate the PH-RTS.ind (ready to send indications) across the L1SAP interface inside osmo-bts. This will trigger the Layer 2 (LAPDm for the control plane, RTP for the voice plane, and OsmoPCU for GPRS) to generate a MAC block and input it into the osmo-bts-trx TDMA scheduler. If OsmoTRX reported N as the current frame number, the actual frame number reported on L1SAP to higher layers will be computed as follows: N + fn-advance + rts-advance The default value of `rts-advance` is 3 (corresponding to 14 milliseconds). Do not change this unless you have a good reason! ===== `osmotrx rx-gain <0-50>` Set the receiver gain (configured in the hardware) in dB. ===== `osmotrx tx-attenuation <0-50>` Set the transmitter attenuation (configured in the hardware) in dB. ===== `osmotrx tx-attenuation oml` Use the Value in the A-bis OML Attribute `MAX_POWER_REDUCTION` as transmitter attenuation. ==== at the 'PHY Instance' configuration node ===== `slotmask (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0)` Configure which timeslots should be active on this TRX. Normally all timeslots are enabled, unless you are running on a cpu-constrained deeply embedded system. ===== `osmotrx maxdly <0-31>` Set the maximum delay for received symbols (in number of GSM symbols). == `osmo-bts-octphy` for Octasic OCTPHY-2G The Octasic OCTPHY-2G is a GSM PHY implementation inside an Octasic proprietary 24-core DSP called OCTDSP. This DSP has a built-in Gigabit Ethernet interface, over which it exchanges PHY-layer primitives in raw Ethernet frames with the upper layers running on another CPU attached to the same Ethernet. Those primitives are described in a set of C-language header files. OsmoBTS implements the raw Ethernet frame based primitives as well as the associated transport protocol (OKTPKT/OCTVC1) in the `osmo-btso-octphy` bts_model code. You can run the `osmo-bts-octphy` on any system connected to the same Ethernet as the OCTDSP running the OCTPHY. This can be either an embedded ARM or x86 SoM part of the OCTBTS hardware, or it can be any other Linux system attached via an Ethernet switch. Each OCTDSP running OCTSDR-2G offers a set of primitives part of a OCTPKT session, which is mapped to an OsmoBTS PHY link. Depending on the OCTSDR-2G software version, you may create multiple software TRX by creating multiple OsmoBTS PHY instances inside that PHY link. Multiple DSPs may exist in one circuit board, then each of the DSPs is interfaced by one OsmoBTS PHY link, and each of them may have one or more OsmoBTS PHY instances creating a Multi-TRX configuration. == `osmo-bts-litecell15` for Nutaq/Nuran LiteCell 1.5 The Nutaq/Nuran LiteCell 1.5 implements a dual-transceiver GSM BTS based on a mixed ARM/DSP/FPGA architecture. The PHY layer is implemented on DSP/FPGA and similar to that of the sysmoBTS: It exchanges primitives described in a set of C-language header files over message queues between the ARM and the DSP. This interface is implemented in the `osmo-bts-litecell15` bts_model of OsmoBTS. You would run `osmo-bts-litecell15` on the ARM/Linux processor of the Litecell 1.5. The two transceivers of the Litecell 1.5 each have their own set of DSP message queues. Each set of message queues is wrapped into one OsmoBTS PHY link, offering one OsmoBTS PHY instance. The Litecell 1.5 PHY supports a direct PHY interface to OsmoPCU, reducing the latency and amount of primitives that OsmoBTS would otherwise need to pass through from the PHY message queues to the PCU socket and vice-versa. === `osmo-bts-trx` specific VTY commands For a auto-generated complete syntax reference of the VTY commands, please see the associated _OsmoBTS VTY reference manual_ <>. The section below only lists the most important commands. ==== at the 'SHOW' node ===== `show phy <0-255> system-information` Show information about the hardware platform, DSP and OCTPHY-2G software version. ===== `show phy <0-255> rf-port-stats <0-1>` Show information about the RF port interfaces. ===== `show phy <0-255> clk-sync-stats` Show information about the clock synchronization manager. ==== at the 'PHY' configuration node ===== `octphy hw-addr HWADDR` Specify the Ethernet hardware address (mac address) of the DSP running the OCTPHY-2G software for this PHY link. ===== `octphy net-device NAME` Specify the Ethernet network device (like `eth0`) through which the DSP can be reached from OsmoBTS. ===== `octphy rf-port-index <0-255>` Specify which RF port should be used for this PHY link. ===== `octphy rx-gain <0-73>` Configure the receiver gain in dB. ===== `octphy tx-attenuation <0-359>` Configure the transmitter attenuation in quarter-dB == `osmo-bts-virtual` for Virtual Um Interface This is a special BTS model used for research, simulation and testing. Rather than communicating over a wireless RF interface, the GSM Um messages are encapsulated over GSMTAP/UDP/IP. The Virtual Um interface (i.e. virtual radio layer) between OsmoBTS and OsmocomBB allows us to run a complete GSM network with 1-N BTSs and 1-M MSs without any actual radio hardware, which is of course excellent for all kinds of testing scenarios. The Virtual Um layer is based on sending L2 frames (blocks) encapsulated via GSMTAP UDP multicast packets. There are two separate multicast groups, one for uplink and one for downlink. The multicast nature simulates the shared medium and enables any simulated phone to receive the signal from multiple BTSs via the downlink multicast group. In OsmoBTS, this is implemented via the `osmo-bts-virtual` BTS model. Setting up OsmoBTS in its `osmo-bts-virtual` flavor isn't really much different from setting it up with real hardware. The amount of required configuration at the BTS configuration file is (as always) very minimal, as in the GSM network architecture provides almost all relevant configuration to the BTS from the BSC. An example configuration file is provided as part of the osmo-bts source code: `doc/examples/virtual/osmobts-virtual.cfg` For more information see http://osmocom.org/projects/cellular-infrastructure/wiki/Virtual_Um === `osmo-bts-virtual` specific VTY commands For a auto-generated complete syntax reference of the VTY commands, please see the associated _OsmoBTS VTY reference manual_ <>. The section below only lists the most important commands. ==== at the 'PHY' config node ===== `virtual-um net-device NETDEV` Configure the network device used for sending/receiving the virtual Um interface messages (e.g. `eth0`). ===== `virtual-um ms-udp-port <0-65535>` Configure the UDP port used for sending virtual Um downlink messages towards the MS (default: GSMTAP 4729). ===== `virtual-um ms-multicast-group GROUP` Configure the IP multicast group used for sending virtual Um downlink messages towards the MS (default: 239.193.23.1) ===== `virtual-um bts-udp-port <0-65535>` Configure the UDP port used for receiving virtual Um uplink messages from the MS (default: GSMTAP 4729). ===== `virtual-um bts-multicast-group GROUP` Configure the IP multicast group used for receiving virtual Um uplink messages from the MS (default: 239.193.23.2)