# Bridge Instance PEER and XLXPEER Examples

`PEER` and `XLXPEER` are bridge-instance features. They should normally be
configured on a `bridge.py` instance, not on the main `bridge_master.py`
FreeDMR master.

The main FreeDMR master intentionally skips non-echo `PEER` and `XLXPEER`
sections. Use a bridge instance when connecting external systems, then route
selected traffic between that bridge instance and the main FreeDMR server.

The FreeDMR wiki has the operator guidance:

- `Making PEER connections (XLX and HBP)`
- `Setup a Bridge instance`
- `Optimise performance and CPU on a busy system connected to FreeDMR Network`

## XLXPEER

`XLXPEER` connects a bridge instance to an XLX module. In FreeDMR deployments
this is primarily used for links to D-Star and AMBE-stick transcoder systems.
It creates the XLX connection only; routing is still controlled by `rules.py`.

```ini
[XLX-1]
MODE: XLXPEER
ENABLED: False
LOOSE: True
EXPORT_AMBE: False
IP:
PORT: 54002
MASTER_IP: 172.16.1.1
MASTER_PORT: 62030
PASSPHRASE: passw0rd
CALLSIGN: W1ABC
RADIO_ID: 312000
RX_FREQ: 449000000
TX_FREQ: 444000000
TX_POWER: 25
COLORCODE: 1
SLOTS: 1
LATITUDE: 38.0000
LONGITUDE: -095.0000
HEIGHT: 75
LOCATION: Anywhere, USA
DESCRIPTION: XLX bridge
URL: www.example.org
SOFTWARE_ID: 20170620
PACKAGE_ID: MMDVM_FreeDMR
GROUP_HANGTIME: 5
# 4000 + module letter position, e.g. A = 4001, D = 4004.
XLXMODULE: 4004
USE_ACL: True
SUB_ACL: DENY:1
TGID_TS1_ACL: PERMIT:ALL
TGID_TS2_ACL: PERMIT:ALL
```

Example local bridge rule:

```python
BRIDGES = {
    235: [
        {'SYSTEM': 'XLX-1', 'TS': 2, 'TGID': 9, 'ACTIVE': True,
         'TIMEOUT': 2, 'TO_TYPE': 'NONE', 'ON': [], 'OFF': [], 'RESET': []},
    ],
}
```

To carry the same traffic onward over an FBP/OBP link, include that link in the
same bridge rule using the FreeDMR talkgroup as the target.

## PEER

`PEER` connects outward using HomeBrew Protocol as a peer. Consider this
carefully. For network-to-network links, OpenBridge/FBP is usually the better
fit. Always make sure you have permission to connect to the external system.

```ini
[PEER-1]
MODE: PEER
ENABLED: False
LOOSE: False
EXPORT_AMBE: False
IP:
PORT: 54001
MASTER_IP: 172.16.1.1
MASTER_PORT: 54000
PASSPHRASE: homebrew
CALLSIGN: W1ABC
RADIO_ID: 312000
RX_FREQ: 449000000
TX_FREQ: 444000000
TX_POWER: 25
COLORCODE: 1
SLOTS: 1
LATITUDE: 38.0000
LONGITUDE: -095.0000
HEIGHT: 75
LOCATION: Anywhere, USA
DESCRIPTION: HBP peer bridge
URL: www.example.org
SOFTWARE_ID: 20170620
PACKAGE_ID: MMDVM_FreeDMR
GROUP_HANGTIME: 5
OPTIONS:
USE_ACL: True
SUB_ACL: DENY:1
TGID_TS1_ACL: PERMIT:ALL
TGID_TS2_ACL: PERMIT:ALL
```

Example local bridge rule:

```python
BRIDGES = {
    235: [
        {'SYSTEM': 'PEER-1', 'TS': 2, 'TGID': 235, 'ACTIVE': True,
         'TIMEOUT': 2, 'TO_TYPE': 'NONE', 'ON': [], 'OFF': [], 'RESET': []},
    ],
}
```

Generally, do not route `PEER` connections onward to OpenBridge/FBP. If you want
to bridge networks, use OpenBridge/FBP for that connection.

## Bridge Instance Pattern

A bridge instance usually has its own config and rules file, for example:

```yaml
freedmr-bridge:
  container_name: freedmr-bridge
  depends_on:
    - freedmr
  volumes:
    - '/etc/freedmr/freedmr-bridge.cfg:/opt/freedmr/freedmr.cfg'
    - '/etc/freedmr/rules-bridge.py:/opt/freedmr/rules.py'
    - '/etc/freedmr/json/:/opt/freedmr/json/'
  image: 'gitlab.hacknix.net:5050/hacknix/freedmr:latest'
  restart: "unless-stopped"
  environment:
    - 'BRIDGE_SERVER=1'
```

On the main FreeDMR instance, add one FBP/OBP link to the bridge instance. Then
put the external `PEER` / `XLXPEER` definitions and matching `rules.py` routes
on the bridge instance.

This keeps external connectors away from the main HBP access server and matches
the FreeDMR operational guidance for busy systems.