Interoperability Repository

Interoperability Repository

Interoperability Repository

The Things Stack expects the root of interoperability repository to contain config.yml, which contains various interoperablity configuration options:

join-servers:                 # list of Join Server interoperability configurations,
                              # used to map a JoinEUI to the Join Server
  - file: './path/js.yml'    # relative path to a file containing Join Server configiration
    join-euis:                # list of Join EUI prefixes the Join Server should handle
    - '11aa000000000000/16'

All paths are relative to the file they are defined in, that is example/js.yml defined in interopconf/config.yml is expected to be located at interopconf/example/js.yml.

For join-servers, in case Join EUI prefixes overlap, the most specific prefix takes precedence.

The Things Stack servers always first try cluster-local Join Server and if it’s not found or the device is not found, fallback to the external one via interoperability.

0000000000000000/0 prefix matches all JoinEUIs, while being the least specific, hence it always matches last. Use this prefix if you wish to define a “fallback” Join Server interoperability configuration.

For example, consider config.yml as follows:

join-servers:
  - file: './example/js.yml'
    join-euis:
    - 'abcd000000000000/16'
    - 'dcba000000000000/16'

  - file: './fallback/js.yml'
    join-euis:
    - '0000000000000000/0'

A configuration like this would make Join Server requests for JoinEUIs starting with ABCD or BCDA to be handled by Join Server defined at example/js.yml in interoperability mode and all other ones to be handled by Join Server defined at fallback/js.yml.

The Join Server configuration provides means to configure how the components interact with the Join Server. The configuration supports multiple options:

fqdn: 'thethings.example'                 # FQDN of the Join Server, if unset, it is resolved via LoRa Alliance DNS
port: 12345                               # port to connect at, if unset, 443 is used
protocol: 'BI1.0'                         # protocol to use - one of BI1.0 or BI1.1
paths:                                    # custom URI paths to use for various requests, if unset, the FQDN is used
  join: 'some/path'                       # the URI path to use for JoinReq
  rejoin: 'some/other/path'               # the URI path to use for RejoinReq
  app-s-key: 'other/path'                 # the URI path to use for AppSKeyReq
  home-ns: 'somepath'                     # the URI path to use for HomeNSReq
tls:                                      # TLS configuration to use
  root-ca: 'path/to/clientca.pem'         # path to client CA
  certificate: 'path/to/clientcert.pem'   # path to client TLS certificate
  key: 'path/to/clientkey.pem'            # path to client TLS key
headers:                                  # HTTP headers to send, defined as key-value map
  SomeHeader: 'SomeValue'

Interoperability with Semtech Join Server

An example interoperability repository supporting Semtech Join Server could look like this:

  • config.yml:

    join-servers:
    - file: './semtech/js.yml'
    join-euis:
    - 'ffffffbb00000000/32'
    - '0016c00000000000/24'
    
    # Other Join Servers, e.g. The Things Industries
    # - file: './tti/js.yml'
    #   join-euis:
    #   - '70b3d57ed0000000/40'
  • semtech/js.yml:

    fqdn: 'js.loracloud.com'
    port: 7009
    protocol: 'BI1.0'
    paths:
    join: 'api/v1/rens/rens-1::2/lbi_joinreq'   # replace 'rens-1::1' by the RENS issued by Semtech
    tls:
    root-ca: './ca.pem'                         # path to the client CA issued by Semtech
    certificate: './cert.pem'                   # path to the client TLS certificate issued by Semtech
    key: './key.pem'                            # path to the client TLS key issued by Semtech