========================
Concentrator Design (v2)
========================

This section lists the available object types and fields, along with their possible values, as understood by Station when parsing configuration files.  The semantics of the fields are discussed elsewhere (see the documentation for each relevant radio board).  Here we briefly discuss only the additional fields or extensions that are specific to LoRa Basics™ Station.

A configuration need not specify any frequencies for, or specifically enable, the ``IFCONF`` or ``RFCONF`` objects.  This information is submitted by the LNS based on the channel plan assigned to a gateway.  The channel-plan settings are merged with the local configuration before the concentrator board is initialized.

The concentrator configuration is embedded in either the ``station.conf`` or ``slave-N.conf`` file as follows:

.. code-block:: javascript

 {
   ...                    // possibly other fields e.g. "station_conf"
   "radio_conf"  : [ BOARD, .. ]
 }


BOARD Object
------------

.. code-block:: javascript

 {
   "device"        : STRING   // station-specific
   "pps"           : BOOL     // station-specific
   "loramac_public": BOOL
   "clksrc"        : INT
   "board_rx_freq" : INT
   "board_rx_bw"   : INT
   "full_duplex"   : BOOL
   "board_type"    : "master" | "slave"
   "FSK_sync"      : STRING     // hexdigits encoding 1-8 bytes
   "calibration_temperature_celsius_room": INT(-128..127)
   "calibration_temperature_code_ad9361" : INT(0..255)
   "dsp_stat_interval" : INT(0..255)
   "nb_dsp"        : INT
   "aes_key"       : STRING     // hexdigits encoding 16 bytes
   "rf_chain_conf" : [ RFCHAINCONF, .. ]
   "SX1301_conf"   : [ SX1301CONF, .. ]
   "lbt_conf"      : LBTCONF
 }

The ``device`` field specifies the SPI device, which is used to communicate with the radio board.  If multiple radio boards are used, the wildcard character (``?``) is replaced with the actual board index.  The board index is inferred from the position inside the ``radio_conf`` array.

If the gateway has a PPS (for example, from a GPS device or other source), the concentrator board that has access to this signal must have the field ``pps`` set to *true*.  One and only one board must have this field set to *true*.

..  note::

	Stations do not require access to a GPS device to maintain a global GPS time for Class B operation.  A PPS aligned with the GPS time is sufficient.


SX1301CONF Object
-----------------

.. code-block:: javascript

 {
   "chip_enable"      : BOOL
   "chip_center_freq" : INT
   "chip_rf_chain"    : INT
   "chan_multiSF_X"   : CHANCONF   // where X in {0..7}
   "chan_LoRa_std"    : CHANCONF
   "chan_FSK"         : CHANCONF
 }


CHANCONF Object
---------------

.. code-block:: javascript

 {
   "chan_rx_freq"  : INT
   "bandwidth"     : INT(125000,250000,50000)
   // if under fields "chan_multiSF_0".."chan_multiSF_7"
   "spread_factor" : INT(7..12)
   // if under field "chan_LoRa_std"
   "spread_factor" : "N-M"        // N,M in {7..12} and N <= M
   // "spread_factor" must be absent if under field "chan_FSK"
   // valid only if under field "chan_FSK"
   "bit_rate"      : INT
 }


LBTCONF Object
--------------


.. code-block:: javascript

 {
   "enable" : BOOL
   "rssi_target" : INT(-128..127)
   "rssi_shift"  : INT(0..255)
   "chan_cfg"    : [ .. ]
 }

.. note::

	The ``chan_cfg`` field must not be specified in a ``station.conf`` file.  This data is automatically generated from the channel plan submitted to the Station by the LNS.


RFCHAINCONF Object
------------------

.. code-block:: javascript

 {
   "rx_enable"    : BOOL
   "tx_enable"    : BOOL
   "rssi_offset"  : INT
   "rssi_offset_coeff_a"  : INT
   "rssi_offset_coeff_b"  : INT
   "tx_freq_min"  : INT
   "tx_freq_max"  : INT
   "tx_lut"       : [ TXLUT, .. ]
   "txpow_adjust" : INT
   "antenna_type" : "omni" | "sector"
 }

All of the fields within ``RFCONF`` are optional. Absent fields are read as *false* or zero.  If ``antenna_type`` or ``type`` is missing, their values are undefined.  The ``txpow_adjust`` field is simply an alias for ``antenna_gain``.

Stations target a specific output power to be dissipated.  The values of the fields ``txpow_adjust`` and ``antenna_gain`` are subtracted from this target value to account for any gains by the antenna and any losses by the cable.

The ``antenna_type`` field specifies the nature of the antenna.  The response to an uplink frame received via a sector antenna is always sent back over the same antenna.  This is also the preferred behavior for an antenna labeled ``omni``.  If the antenna is blocked (for instance, due to duty-cycle limitations or being busy with another transmission), the Station may transfer the downlink transmission to another ``omni`` antenna.


TXLUT Object
------------

.. code-block:: javascript

 {
   "rf_power"      : INT(-128..127)
   "fpga_dig_gain" : INT(0..255)
   "ad9361_atten"  : INT(0..65535)
   "ad9361_auxdac_vref"   : INT(0..255)
   "ad9361_auxdac_word"   : INT(0..65535)
   "ad9361_tcomp_coeff_a" : INT(-32768..32767)
   "ad9361_tcomp_coeff_b" : INT(-32768..32767)
 }


Antenna Configurations
----------------------

The Concentrator Design v2 is equipped with two radio front-ends. This enables various multi-antenna scenarios. The most common of these are discussed in this section.

Single Antenna
~~~~~~~~~~~~~~

::

  // Single Antenna on RF-0
  "rf_chain_conf" : [
    {"rx_enable": true , "tx_enable": true , ..},
    {"rx_enable": false, "tx_enable": false, ..}
  ]

In the single-antenna configuration, the second RF chain is disabled. Reception and transmission on all channels is done through a single RF chain.


Multi-Antenna - Full Diversity / Sectorization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

  // Full Diversity -> TX diversion to another antenna allowed
  "rf_chain_conf" : [
    {"rx_enable": true, "tx_enable": true, "antenna_type": "omni", ..},
    {"rx_enable": true, "tx_enable": true, "antenna_type": "omni", ..}
  ]

  // Sectorization -> TX strictly on the same antenna
  "rf_chain_conf" : [
    {"rx_enable": true, "tx_enable": true, "antenna_type": "sector", ..},
    {"rx_enable": true, "tx_enable": true, "antenna_type": "sector", ..}
  ]


Enabling both transmission and reception on both RF chains allows for antenna diversity configurations. This can improve performance for the reception of mobile devices where fast-fading may cause signal intensity degradation on a single antenna. A multi-antenna setup can also be used for cell sectorization, improving the overall capacity of the gateway.
On a single-board, a two-chip gateway platform Station will automatically assume full antenna diversity for frequency plans which can be allocated on a single SX1301 chip. This is done by duplicating the single-chip frequency plan on both chips while assigning them to different RF chains. By default Station prioritizes the same antenna through which the associated uplink was received for an outbound transmission. If the preferred antenna is blocked, a transmission may be diverted to another antenna in the case of full diversity. This diversion does not occur in the case of sectorization.


Multi-Antenna - Full-duplex
~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

  // RX on RF-0, TX on RF-1
  "rf_chain_conf" : [
    {"rx_enable": true , "tx_enable": false, ..},
    {"rx_enable": false, "tx_enable": true , ..}
  ]

By default, LoRaWAN® gateways operate in *half-duplex* mode. This means that the gateway cannot receive incoming messages during outbound transmissions. *Full-duplex* means that reception is still possible during ongoing transmissions. This is achieved by dedicating each antenna to either reception or transmission.