# Downloaded from https://bitbucket.org/wisunalliance/test-bed-unit-api
# Test Bed Unit API
# Copyright © Wi-SUN Alliance 2024 - 2025
#
# Conventions:
#
# This API has grown organically over the course of multiple rounds of FAN
# development. As such, it doesn't have a perfectly consistent design. To try
# and consolidate around one design language, the following conventions are
# proposed for new changes, where those changes don't break backwards
# compatibility.
#
# * /config root for all endpoints affecting a change in device configuration.
# * /command root for all endpoints affecting an operation on/from a device.
# * ROOT/ for endpoints valid on all devices (or at least, multiple groups.)
# * ROOT/ROLE/ for endpoints only valid on devices of some role (LBR, LR, LFN)
# * ROOT/ROLE/FEATURE/ or /ROOT/FEATURE/ categorises multiple endpoints under
#   one feature moniker. E.g., all PHY endpoints are found under /config/phy.
#
# Response Codes:
#
# In general, adhere to the well established web standards.
# https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
#
# 200 - Success.
#
# 4xx - Error on the part of the client (TBC).
# 400 - Bad Request. Likely due to invalid parameters supplied.
#
# 5xx - Error on the part of the server (TBU).
# 500 - Internal Server Error. Something went wrong with the TBU, but it cannot
#       tell the caller what it was. A catch-all for unhandled exceptions.
# 501 - Not Implemented. This TBU does not implement some feature which is
#       endemic to the endpoint.

swagger: '2.0'
info:
  version: 1.1.17
  title: TBU API
  description: Test Bed Unit API. NOTE all IPv6 address strings are formatted per RFC 5952. Note that optional object properties, when not included in messaging and unless noted otherwise, will assume their default values as specified in the FAN TPS. Copyright © Wi-SUN Alliance 2024 - 2025.
basePath: /Wi-SUN/TBU/1.1.17
schemes:
  - https
  - http
consumes:
  - application/json
produces:
  - application/json
paths:

################################################################################
# Run Mode Endpoints
################################################################################

  /runMode/{mode}:
    put:
      description: Set the run mode of the TBU's FAN stack
      parameters:
      - name: mode
        description: There are three possible run modes, stop (0), start (1), and suspend (2) with five valid transitions between. A stopped device MUST clear all state and configuration memory, returning to power-on reset (POR) state. If the device was running before being stopped, it MUST NOT deregister from the network, instead it should silently and immediately terminate. A started (running) device operates normally. A suspended device MUST maintain its state data (FAN 1.1 TPS section 6.5.6), but MUST clear its TBU configuration as the TBC will reconfigure any suspended devices on their resumption. Identically to a stopped device, a suspended device MUST NOT deregister from the network. When a suspended device resumes (is set to runMode=1), it MUST restore and use its saved state. Only the following transitions are defined and valid. A stopped device can transition into the start mode once configured, but never into suspend mode. A running device may transition into either stop (clearing its state) or suspend (storing its state) modes. A suspended device may transition into either stop (clearing its state) or start modes (restoring its state). A TBU is assumed to be in the stopped state on boot.
        in: path
        required: true
        type: integer
        format: int32
        enum: [0, 1, 2]
      responses:
        200:
          description: runMode change was executed successfully
        400:
          description: Illegal runMode was specified
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Illegal transition was specified
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

################################################################################
# Configuration Endpoints
################################################################################

  /config/phy:
    put:
      description: Configure the PHY layer of the FAN stack
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/PhyConfig'
      responses:
        200:
          description: PHY successfully configured.
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/phy/modeID:
    put:
      description: Configure the PHY layer of the FAN stack. FAN 1.1 alternative to /config/phy.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/PhyConfigUsingModeID'
      responses:
        200:
          description: PHY successfully configured.
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/phy/modeSwitch/modeIDs:
    put:
      description: Configure the PHY Operating Mode IDs advertised by a given device. The device's base PHY MUST be configured first, before its POM-IE. A device MUST NOT advertise any modes not configured by this endpoint.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/phyOperatingModeIDs'
      responses:
        200:
          description: PHY Operating Modes successfully configured.
        501:
          description: This device does not support one or more of the given POMs!
          schema:
            $ref: '#/definitions/ErrorResponse'
        502:
          description: This device does not support the optional mode switch feature!
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/phy/modeSwitch/mdrCommandCapable/{enableMDRCmd}:
    put:
      description: Configure a device's ability to accept an MDR MAC Command. Test bed units are expected to support MDR MAC Commands by default!
      parameters:
      - name: enableMDRCmd
        description: True to enable and advertise receipt of the MDR MAC Command, false to disable support.
        in: path
        required: true
        type: boolean
      responses:
        200:
          description: MDR Command Capable flag set or cleared successfully.
        501:
          description: This device does not support MDR MAC Commands!
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/chanPlan/regId:
    put:
      description: Configure both the unicast and bcast channel plan using Regulatory Domain and Channel Plan ID.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/chanPlanRegId'
      responses:
        200:
          description: Channel plan successfully configured.
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  /config/chanPlan/regOp:
    put:
      description: Configure both the unicast and bcast channel plan using Regulatory Domain and Operating Class (compatible with FAN 1.0).
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/chanPlanRegOp'
      responses:
        200:
          description: Channel plan successfully configured.
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  /config/chanPlan/explicit:
    put:
      description: Configure both the unicast and bcast channel plan using ch0, channel spacing, and number of channels.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/chanPlanExplicit'
      responses:
        200:
          description: Channel plan successfully configured.
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  /config/chanPlan/fixed:
    put:
      description: Configure both the unicast and bcast channel plan to a single fixed channel.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/chanPlanFixed'
      responses:
        200:
          description: Channel plan successfully configured.
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  /config/chanPlan/unicast:
    put:
      description: Configure the unicast channel plan specifics for FFNs. This method may only be issued to an FFN.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/unicastChanPlan'
      responses:
        200:
          description: Channel plan successfully configured.
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  /config/chanPlan/bcast:
    put:
      description: Configure the broadcast channel plan specifics for FFNs. This method may only be issued to a Border Router.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/bcastChanPlan'
      responses:
        200:
          description: Channel plan successfully configured.
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  /config/whitelist:
    put:
      description: Configure a device's whitelist. When a device is configured with a non-empty whitelist, only frames received from EUI64 addresses within the whitelist are passed up to the MAC layer for processing. If an empty whitelist is configured, the device's whitelist is disabled.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/MacAddresses'
      responses:
        200:
          description: Device successfully configured.
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/ipAddresses:
    get:
      description: Returns all unicast IPv6 addresses configured on the device's FAN interface (LL, ULA, GUA).
      responses:
        200:
          description: Unicast IPv6 addresses configured. IPv6 address strings are formatted per RFC 5952.
          schema:
            type: array
            items:
              type: string
              example: "FF02::1"
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/securityKeys:
    get:
      description: Return the security keys populated on the device.
      responses:
        200:
          description: The security keys populated on the device.
          schema:
            $ref: '#/definitions/GroupTransientKeys'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/dodagRoutes:
    get:
      description: Return the DODAG downward routes populated on a Border Router (indicating devices joined to the mesh). This method may only be issued to a Border Router.
      responses:
        200:
          description: The downward routes populated on a Border Router.
          schema:
            type: array
            items: {
              $ref: '#/definitions/DodagRouteEntry'
            }
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/neighborTable:
    get:
      description: Return the Neighbor Table populated on a Router.
      responses:
        200:
          description: The Neighbor Table populated on the Router.
          schema:
            type: array
            items: {
              $ref: '#/definitions/NeighborTableEntry'
            }
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/preferredParent:
    get:
      description: Return the preferred parent of a specific FAN device. This method may only be issued to a Border Router.
      parameters:
        - in: query
          name: ipAddress
          type: string
          required: true
          description: The IPv6 address of the device to be queried for its preferred parent, formatted per RFC 5952.
      responses:
        200:
          description: The IPv6 address of the preferred parent, formatted per RFC 5952.
          schema:
            type: string
            example: "FF02::1"
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter:
    put:
      description: Configure Border Router specific settings. This method may only be issued to a Border Router.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/BorderRouterConfig'
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        501:
          description: Optional feature is not supported.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/gtks:
    put:
      description: Configure Border Router GTKs and/or LGTKs. This method may only be issued to a Border Router.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/GroupTransientKeys'
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/keyLifetimes:
    put:
      description: Configure Border Router key lifetimes. This method may only be issued to a Border Router. If non-default key lifetimes are needed, this call MUST be issued before setting the L/GTKs with /config/borderRouter/gtks.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/KeyLifetimes'
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/revokeKeys:
    put:
      description: This method may only be issued to a Border Router (supporting the operation described in Step 3 of [FANTPS] section 6.5.2.5 Revocation of Node Access). The Border Router destroys all group keys (GTKs or LGTKs) except the currently active group key, modifies the lifetime of the currently active group key to be (lifetime / REVOCATION_LIFETIME_REDUCTION), and installs the new group key provided by this API method. The GroupTransientKey object indicates the type of group keys (GTK or LGTK) upon which this method acts.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/GroupTransientKey'
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/revokeNodes:
    put:
      description: Destroy the PMK/PTK of the given device EUI(s).
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/MacAddresses'
      responses:
        200:
          description: PMK/PTK of device(s) destroyed.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/informationElements:
    put:
      description: This method may only be issued to a Border Router. It is used to force addition of one or more Information Elements (beyond those normally populated) into the Border Router's subsequently issued PC frames. This method is primarily intended to test unknown IE handling/content within the mesh. All additions and deletions trigger an increment of PAN Version in the PC and LPC, and reset of its trickle timer.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: array
          items: {
            $ref: '#/definitions/BorderRouterInformationElement'
          }
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

    delete:
      description: This method may only be issued to a Border Router. It is used to delete a set of Information Elements from the Border Router's subsequently issued PC frames. This method is primarily intended to test unknown IE handling/content within the mesh. All additions and deletions trigger an increment of PAN Version in the PC and LPC, and reset of its trickle timer.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: array
          items: {
            $ref: '#/definitions/BorderRouterInformationElement'
          }
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/joinMetrics:
    put:
      description: Configure Border Router join metrics (JM-IE). This method may only be issued to a Border Router. As defined in [FANTPS], any change in the JM-IE contents updates the JM-IE Content Version.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: array
          items: {
            $ref: '#/definitions/BorderRouterJoinMetric'
          }
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

    delete:
      description: Remove join metrics from the Border Router JM-IE.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: array
          items: {
            $ref: '#/definitions/BorderRouterJoinMetric'
          }
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/borderRouter/externalResources:
    put:
      description: Configure a Border Router's required external services. This method may only be issued to a Border Router.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/BorderRouterExternalResources'
      responses:
        200:
          description: Border Router successfully configured.
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/router:
    put:
      description: Configure Router specific settings. This method may be issued to any Router device (including Border Routers).
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/RouterConfig'
      responses:
        200:
          description: Router successfully configured.
        400:
          description: Device is not a Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /config/lfn:
    put:
      description: Configure LFN specific settings. This method may only be issued to an LFN.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/LfnConfig'
      responses:
        200:
          description: LFN successfully configured.
        400:
          description: Device is not an LFN.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  # Previously: /config/chanPlan/unicast/lfn
  /config/lfn/chanPlan/unicast:
    put:
      description: Configure LFN unicast channel plan details. This method may only be issued to an LFN.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/unicastChanPlanLfn'
      responses:
        200:
          description: Channel plan successfully configured.
        400:
          description: Device is not an LFN.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

  # Previously: /config/chanPlan/bcast/lfn
  /config/lfn/chanPlan/bcast:
    put:
      description: Configure LFN broadcast channel plan details. This method may only be issued to a Border Router.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/bcastChanPlanLfn'
      responses:
        200:
          description: Channel plan successfully configured.
        400:
          description: Device is not an LBR.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
             $ref: '#/definitions/ErrorResponse'

################################################################################
# Command Endpoints
################################################################################

  /command/nd/enableNS:
    put:
      description: Option for enabling/disabling the transmission of Neighbor Solicitation frames from an FFN router or LFN.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/NDEnableNeighborSolicitations'
      responses:
        200:
          description: Neighbor Solicitation enable successfully configured.
        400:
          description: Device is not a Router or LFN.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Invalid parameter.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/nd/requestRegistrationRefresh:
    post:
      description: Request a device to execute the Registration Refresh Request procedure described in TPS section 6.2.3.1.4.1.
      responses:
        200:
          description: Device will send a Neighbor Advertisement.
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/nd/sendNS:
    post:
      description: Force a router or LFN device to immediately re-register its GUA/ULA using its current lifetime. A router MUST send an NS(ARO), and an LFN MUST send an NS(EARO), to its parent with the lifetime previously configured with its /config/router or /config/lfn endpoint.
      responses:
        200:
          description: Device will send a Neighbour Solicitaion with EARO.
        400:
          description: Device is not a Router or LFN.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/borderRouter/rpl/incrementDodagVersion:
    post:
      description: Increment the RPL DODAG Version Number.
      responses:
        200:
          description: RPL DODAG Version Number incremented successfully
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/borderRouter/rpl/incrementDtsn:
    post:
      description: Increment the border router's RPL DTSN.
      responses:
        200:
          description: RPL DTSN incremented successfully
        400:
          description: Device is not a Border Router.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/lfn/deregisterFromParent:
    put:
      description: Request an LFN to deregister from its parent, following the process described in [FANTPS] Section 6.2.3.1.4.2
      responses:
        200:
          description: Device will send a deregistration request.
        400:
          description: Device is not an LFN.
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/lfn/joinMCGroup:
    post:
      description: Request an LFN to join a multicast group, following the process described in [FANTPS] section 6.2.3.1.4.3.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/MulticastGroup'
      responses:
        200:
          description: Device will initiate multicast group enrollment.
        400:
          description: Device is not an LFN.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

  /command/lfn/leaveMCGroup:
    post:
      description: Request an LFN to leave a multicast group, following the process described in [FANTPS] section 6.2.3.1.4.3.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/MulticastGroup'
      responses:
        200:
          description: Device will initiate multicast group resignation.
        400:
          description: Device is not an LFN.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

################################################################################
# Frame Subscription Endpoints
################################################################################

  /subscription/frames:
    put:
      description: Forward MAC frames to a specified destination (subscribe to a frame stream).
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/FrameSubscription'
      responses:
        200:
          description: Listener successfully subscribed.
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'


  /subscription/frames/hash:
    get:
      description: Get current value of the subscription session hash. Support for this method is OPTIONAL. It was added to detect errors in TBC subscribed frame reception. Likely not needed for FAN 1.1.
      responses:
        200:
          description: The current value of the subscription session SHA256 hash (encoded as hex ASCII ... 64 digits).
          schema:
            type: string
            example: "2C43C95D0F764AAEA9A7CE3CAA48803725A887F48CB3472B7087B0BA8ED98805"
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

################################################################################
# Transmit Endpoints
################################################################################

  /transmitter/udp:
    put:
      description: Transmit a UDP datagram.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/UDPDatagram'
      responses:
        200:
          description: UDP datagram successfully transmitted.
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /transmitter/icmpv6Echo:
    put:
      description: Transmit an ICMPv6 Echo message.
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/ICMPv6Echo'
      responses:
        200:
          description: ICMPv6 Echo message successfully transmitted.
        410:
          description: Requested a mode switch, but didn't provide a PhyModeID.
          schema:
            $ref: '#/definitions/ErrorResponse'
        420:
          description: Sending an LTO-IE requires both an adjustedListeningOffset and an adjustedListeningInterval, with at least one being non-zero.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Unknown error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'

################################################################################
# Miscellaneous Endpoints
################################################################################

  /capabilities/phy/{eui64}:
    get:
      description: Return the PHY capabilites of the device indicated by the EUI64. When the EUI64 parameter is that of the serving device, the serving device's capabilities are returned. Otherwise, the capabilities of the neighbor indicated by the EUI64 are returned.
      parameters:
      - name: eui64
        description: The EUI64 of the device for which capabilities are requested.
        in: path
        required: true
        type: string
      responses:
        200:
          description: The PHY capabilities.
          schema:
            $ref: "#/definitions/PhyCapabilities"
        default:
          description: Unknown error occurred
          schema:
            $ref: '#/definitions/ErrorResponse'

################################################################################
# Data Models
################################################################################

definitions:

  ErrorResponse:
    type: object
    description: API error return code and return code description.
    required:
    - code
    - message
    properties:
      code:
        description: Error code. 0 = unknown error, 1 = both a channel exclusion mask and range were specified, 2 = illegal run mode, 3 = device is not a border router, 4 = device is not a router, 5 = optional feature is not supported.
        type: integer
        format: int32
        enum: [0, 1, 2, 3, 4, 5]
      message:
        description: Failure code description.
        type: string
        example: "Something bad happened"

  PhyConfig:
    type: object
    description: The PHY configuration of a FAN device.
    required:
      - modulation
      - symbolRate
      - modulationIndex
    properties:
      modulation:
        description: 0 = 2FSK
        type: integer
        enum: [0]
      symbolRate:
        description: Symbols per second (ex 50000 for 50K)
        type: integer
        format: integer32
      modulationIndex:
        description: 0 = 0.5, 1 = 1.0
        type: integer
        enum: [0, 1]

  PhyConfigUsingModeID:
    type: object
    description: The PHY configuration of a FAN device (using a mode ID).
    required:
      - basePhyModeID
    properties:
      basePhyModeID:
        description: The base operating mode which MUST be set to a PhyModeID value defined in
          section 5.2 of [PHYTPS].
        type: integer

  phyOperatingModeIDs:
    type: object
    description: A list of PHY Operating Mode IDs to be advertised from a given device in its POM-IE.
    required:
      - modes
    properties:
      modes:
        description: Set as specified in section 5.2 of [PHYTPS].
        type: array
        items:
          type: integer
          example: [5, 38, 54, 70, 86]

  chanPlanRegId:
    type: object
    description: Channel plan specified with Regulatory Domain and ChanPlanID
    required:
      - regDomain
      - chanPlanID
    properties:
      regDomain:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer
      chanPlanID:
        description: MUST be set to one of the ChanPlanID values defined in [PHYTPS].
        type: integer

  chanPlanRegOp:
    type: object
    description: DEPRECATED Channel plan specified with Regulatory Domain and Operating Class
    required:
      - regDomain
      - opClass
    properties:
      regDomain:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer
      opClass:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer

  chanPlanExplicit:
    type: object
    description: Channel plan specified with CH0, channel spacing, number of channels
    required:
    - ch0
    - chanSpacing
    - numChans
    properties:
      ch0:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer
      chanSpacing:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer
      numChans:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer

  chanPlanFixed:
    type: object
    description: Set a fixed channel plan.
    required:
    - chanNumber
    properties:
      chanNumber:
        description:  The single fixed channel of operation.
        type: integer

  unicastChanPlan:
    type: object
    description: Unicast channel plan specification for FFNs.
    required:
    - dwellInterval
    - channelFunction
    - excludedChannelRange
    - excludedChannelMask
    properties:
      dwellInterval:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer
      channelFunction:
        description: Set as specified in [FANTPS] US-IE description.
        type: integer
      excludedChannelRange:
        description: An array of beginning-of-range/end-of-range channel pairs. Example [1, 10, 20, 25] indicates channels 1 through 10 are excluded and channels 20 through 25 are excluded. NOTE only one of excludedChannelRange OR excludedChannelMask may be specified, with Excluded Channel Control set accordingly, and the non specified exclusion MUST be indicated as an empty array.
        type: array
        items: {
          type: integer
        }
      excludedChannelMask:
        description: Each octet of the bit mask described in the FAN TPS is placed at the corresponding index of the integer array. Octet 0 is placed at array[0], etc. NOTE only one of excludedChannelRange OR excludedChannelMask may be specified, with Excluded Channel Control set accordingly, and the non specified exclusion MUST be indicated as an empty array.
        type: array
        items: {
          type: integer
        }

  bcastChanPlan:
    type: object
    description: Broadcast channel plan specification. excludedChannelRange and excludedChannelMask are optional (used for FAN 1.0, not used for FAN 1.1)
    required:
    - bcastInterval
    - bcastScheduleId
    - dwellInterval
    - channelFunction
    properties:
      bcastInterval:
        description: Set as specified in [FANTPS] BS-IE description.
        type: integer
      bcastScheduleId:
        description: Set as specified in [FANTPS] BS-IE description.
        type: integer
      dwellInterval:
        description: Set as specified in [FANTPS] BS-IE description.
        type: integer
      channelFunction:
        description: Set as specified in [FANTPS] BS-IE description.
        type: integer
      excludedChannelRange:
        description: An array of beginning-of-range/end-of-range channel pairs. Example [1, 10, 20, 25] indicates channels 1 through 10 are excluded and channels 20 through 25 are excluded. NOTE only one of excludedChannelRange OR excludedChannelMask may be specified, with Excluded Channel Control set accordingly, and the non specified exclusion MUST be indicated as an empty array.
        type: array
        items: {
          type: integer
        }
      excludedChannelMask:
        description: Each octet of the bit mask described in the FAN TPS is placed at the corresponding index of the integer array. Octet 0 is placed at array[0], etc. NOTE only one of excludedChannelRange OR excludedChannelMask may be specified, with Excluded Channel Control set accordingly, and the non specified exclusion MUST be indicated as an empty array.
        type: array
        items: {
          type: integer
        }

  # Note: Breaks from OpenAPI TitleCase style guide to confirm to existing.
  unicastChanPlanLfn:
    type: object
    description: Unicast channel plan specification for FFNs.
    required:
    - listenInterval
    - channelFunction
    - excludedChannelRange
    - excludedChannelMask
    properties:
      listenInterval:
        description: Set as specified in [FANTPS] LUS-IE description; used for the default unicast listen interval.
        type: integer
      channelFunction:
        description: Set as specified in [FANTPS] LCP-IE description.
        type: integer
      excludedChannelRange:
        description: An array of beginning-of-range/end-of-range channel pairs. Example [1, 10, 20, 25] indicates channels 1 through 10 are excluded and channels 20 through 25 are excluded. NOTE only one of excludedChannelRange OR excludedChannelMask may be specified, with Excluded Channel Control set accordingly, and the non specified exclusion MUST be indicated as an empty array.
        type: array
        items: {
          type: integer
        }
      excludedChannelMask:
        description: Each octet of the bit mask described in the FAN TPS is placed at the corresponding index of the integer array. Octet 0 is placed at array[0], etc. NOTE only one of excludedChannelRange OR excludedChannelMask may be specified, with Excluded Channel Control set accordingly, and the non specified exclusion MUST be indicated as an empty array.
        type: array
        items: {
          type: integer
        }
      eapolListenInterval:
        description: An optional, shorter interval used during the EAPOL exchange. When present, to be used for the unicast listen interval during EAPOL transactions. The LFN must change its listen interval to this value  with an LUS-IE in the first EAPOL frame and switch back to the lfnInterval with an LUS-IE in the LPCS frame after the EAPOL transaction.
        type: integer

  # Note: Breaks from OpenAPI TitleCase style guide to confirm to existing.
  bcastChanPlanLfn:
    type: object
    description: Broadcast channel plan specification for LFNs.
    required:
    - bcastInterval
    - bcastSyncPeriod
    properties:
      bcastInterval:
        description: Set as specified in [FANTPS] LBS-IE description.
        type: integer
      bcastSyncPeriod:
        description: Set as specified in [FANTPS] LBS-IE description.
        type: integer

  GroupTransientKeys:
    type: object
    description: Add or update one or more Group Transient Keys (GTK or LGTK) to the Border Router. Keys omitted from this object are not removed. Border Routers should not configure and distribute LGTKs if they do not indicate their support of LFNs in their lfnJoinEnabled parameter.
    properties:
      gtk0:
        description: Group Transient Key 0 (PAN wide)
        type: string
      gtk1:
        description: Group Transient Key 1 (PAN wide)
        type: string
      gtk2:
        description: Group Transient Key 2 (PAN wide)
        type: string
      gtk3:
        description: Group Transient Key 3 (PAN wide)
        type: string
      lgtk0:
        description: LFN Group Transient Key 0
        type: string
      lgtk1:
        description: LFN Group Transient Key 1
        type: string
      lgtk2:
        description: LFN Group Transient Key 2
        type: string

  GroupTransientKey:
    type: object
    description: A single Group Transient Key (GTK or LGTK) populated on the BR.
    required:
    - gtk
    properties:
      gtk:
        description: Group Transient Key
        type: string
      isLgtk:
        description: If omitted or set to false, key is a GTK. If included and set to true, key is an LGTK.
        type: boolean

  KeyLifetimes:
    type: object
    description: Lifetime of the various keys used at the Border Router.
    properties:
      pmkLifetime:
        description: PMK lifetime (minutes) for FFNs.
        type: string
      ptkLifetime:
        description: PTK lifetime (minutes) for FFNs.
        type: string
      gtkLifetime:
        description: GTK lifetime (minutes) for all GTKs.
        type: string
      gtkNewActivationTime:
        description: The time at which the Border Router activates the next GTK prior to expiration of the currently activated GTK. Calculated as (1/gtkNewActivationTime) * GTK_EXPIRE_OFFSET.
        type: integer
      revocationLifetimeReduction:
        description: Factor by which the active GTK lifetime is reduced during node revocation procedures. Reduced lifetime is calculated as (1/gtkRevocationLifetimeReduction) * original lifetime.
        type: integer
      lfnPmkLifetime:
        description: PMK lifetime (minutes) for LFNs.
        type: string
      lfnPtkLifetime:
        description: PTK lifetime (minutes) for LFNs.
        type: string
      lgtkLifetime:
        description: LGTK lifetime (minutes) for all LGTKs.
        type: string
      lgtkNewActivationTime:
        description: The time at which the Border Router activates the next LGTK prior to expiration of the currently activated LGTK. Calculated as (1/lgtkNewActivationTime) * LGTK_EXPIRE_OFFSET.
        type: integer
      lgtkRevocationLifetimeReduction:
        description: Factor by which the active LGTK lifetime is reduced during node revocation procedures. Reduced lifetime is calculated as (1/lgtkRevocationLifetimeReduction) * original lifetime.
        type: integer

  BorderRouterConfig:
    type: object
    description: Several Border Router "administrative" settings.
    required:
      - panId
      - panSize
      - useParentBcastSched
      - routingMethod
      - networkName
    properties:
      panId:
        description: Set as specified in [FANTPS] PAN Advertisement frame description.
        type: integer
      panSize:
        description: Set as specified in [FANTPS] PAN-IE description.
        type: integer
      useParentBcastSched:
        description: Set as specified in TPS PAN-IE description.
        type: boolean
      routingMethod:
        description: Set as specified in [FANTPS] PAN-IE description.
        type: integer
      networkName:
        description: Set as specified in [FANTPS] NETNAME-IE description.
        type: string
      sixLowpanMtu:
        description: The 6LoWPAN MTU to be used by this router.
        type: integer
      lfnJoinEnabled:
        description: True if LFN joins to the PAN and to this border router are allowed, False otherwise.
        default: false
        type: boolean
      mplSeedLength:
        description: The MPL seed-id length (S-field). An unsigned two-bit integer equal to either 0 or 3, where 0 indicates the seed-id is elided and is the IPv6 source address, and 3 indicates the seed-id is the 128-bit ULA/GUA of the source. [RFC7731, FANTPS-1.1v06-d7]
        type: integer
        minimum: 0
        maximum: 3
        default: 3

  BorderRouterExternalResources:
    type: object
    description: A description of the required, external resources of a border router.
    required:
      - authServerAddress
      - authServerSecret
      - dhcpServerAddress
    properties:
      authServerAddress:
        description: The IPv6 address of the Authentication server to be used by the Border Router, formatted per RFC 5952.
        type: string
      authServerSecret:
        description: The access secret for the defined authentication server.
        type: string
      dhcpServerAddress:
        description: The IPv6 address of the DHCPv6 server to be used by the Border Router, formatted per RFC 5952.
        type: string

  RouterConfig:
    type: object
    description: Several TPS "administrative" (fixed pre-deployment) router setting.
    required:
    - routingMethod
    - networkName
    - panSizeOffset
    - routingCostOffset
    properties:
      routingMethod:
        description: Set as specified in the [FANTPS] PAN-IE description.
        type: integer
      networkName:
        description: Set as specified in the [FANTPS] NETNAME-IE description.
        type: string
      panSizeOffset:
        description: An offset to be added to the Pan Size advertised by this device.
        type: integer
      routingCostOffset:
        description: An offset to be added to the Routing Cost advertised by this device.
        type: integer
      sixLowpanMtu:
        description: The 6LoWPAN MTU to be used by this router.
        type: integer
      gtkMaxMismatch:
        description: Maximum time between a SUP detecting a GTKHASH mismatch and the SUP initiating Msg1 of the authentication flow (causing the BR to initiate a Group Key handshake with the SUP).
        type: integer
      lgtkMaxMismatch:
        description: Maximum time between a SUP detecting a LGTKHASH mismatch and the SUP initiating Msg1 of the authentication flow (causing the BR to initiate a Group Key handshake with the SUP).
        type: integer
      ndAddressRegistrationLifetime:
        description: 16-bit unsigned integer. The lifetime, in minutes, of the router's address registration. [RFC 8505] and [RFC 9010]
        type: integer
        default: 40
      lfnJoinEnabled:
        description: True if LFN joins to this router are enabled, False otherwise.
        default: false
        type: boolean
      lfnPanTimeout:
        description: Interval, in minutes, after which an FFN parent must disable LFN broadcast messaging if the FFN parent is unable to communicate with its border router.
        type: integer
        default: 30
      mplSeedLength:
        description: The MPL seed-id length (S-field). An unsigned two-bit integer equal to either 0 or 3, where 0 indicates the seed-id is elided and is the IPv6 source address, and 3 indicates the seed-id is the 128-bit ULA/GUA of the source. [RFC7731, FANTPS-1.1v06-d7]
        type: integer
        minimum: 0
        maximum: 3
        default: 3

  LfnConfig:
    type: object
    description: LFN specific settings.
    required:
      - routingMethod
      - networkName
      - sixLowpanMtu
      - lgtkMaxMismatch
    properties:
      routingMethod:
        description: Set as specified in the [FANTPS] PAN-IE description.
        type: integer
      networkName:
        description: Set as specified in the [FANTPS] NETNAME-IE description.
        type: string
      sixLowpanMtu:
        description: The 6LoWPAN MTU to be used by this LFN.
        type: integer
      lgtkMaxMismatch:
        description: Maximum time between a SUP detecting a LGTKHASH mismatch and the SUP initiating Msg1 of the authentication flow (causing the BR to initiate a Group Key handshake with the SUP).
        type: integer
      ndAddressRegistrationLifetime:
        description: 16-bit unsigned integer. The lifetime, in minutes, of the LFN's GUA/ULA registration. [RFC 6775 Section 4.1]
        type: integer
        default: 2160

  NDEnableNeighborSolicitations:
    type: object
    description: Enable or disable NS frame emission for IPv6 Neighbor Discovery
    required:
      - enableNeighborSolicitations
    properties:
      enableNeighborSolicitations:
        description: Whether or not to enable Neighbor Solicitation (NS) frames. Default is enabled.
        type: boolean
        default: true

  MacAddresses:
    type: object
    description: An array of EUI64 addresses.
    required:
    - macAddressList
    properties:
      macAddressList:
        description: An array of EUI64 addresses.
        type: array
        items:
          type: string

  DodagRouteEntry:
    type: object
    description: A DODAG downward route.
    properties:
      route:
        description: The ULA/GUA of the downward route to the device.
        type : string

  NeighborTableEntry:
    type: object
    description: A Neighbor Table Entry. There will be one entry per neighbor. For entries that refer to an LFN, fields that are not applicable to LFNs (e.g., etx, rsl, panSize, routingCost) MUST be set to zero.
    required:
      - eui64
      - etx
      - rsl
      - rssi
      - panSize
      - routingCost
      - ipAddresses
      - timeSinceLastRx
      - isParentStatus
    properties:
      eui64:
        description: The EUI64 of the neighbor device.
        type: string
      etx:
        description: ETX EWMA of the neighbor device.
        type: integer
      rsl:
        description: RSL EWMA of the neighbor device.
        type: integer
      rssi:
        description: Raw RSSI for the neighbor device.
        type: integer
      panSize:
        description: The device's reported PAN size.
        type: integer
      routingCost:
        description: The device's reported routing cost.
        type: integer
      ipAddresses:
        description: The IP addresses of the neighbor device. IPv6 address strings are formatted per RFC 5952.
        type: array
        items:
          type: string
          example: "FF02::1"
      timeSinceLastRx:
        description: msec since last Rx from the neighbor device.
        type: integer
        format: integer32
      isParentStatus:
        description: The RPL parent status of the neighbor. 0 means the neighbor is not a RPL parent, 1 means the neighbor is a RPL parent, 2 means the neighbor is the preferred RPL parent.
        type: integer
        enum: [0, 1, 2]

  PhyCapabilities:
    type: object
    description: The PHY capabilities of a device (modeled after POM-IE)
    properties:
      mdrCmdCapable:
        description: MUST be set to true if the device implements the MDR Command capability, otherwise false.
        type: boolean
      phyOpModes:
        description: The list of PHY Operating modes supported by the device. Each entry in the array MUST be a PhyModeID value defined in section 5.2 of [PHYTPS]
        type: array
        items:
          {
            type: integer
          }

  FrameSubscription:
    type: object
    description: A subscription to configure a FAN device to echo received MAC frames to a designated UDP listener's IP address / port number. The PCAP Next Generation (pcapng) Capture File Format (draft-tuexen-opsawg-pcapng) MUST be used to encapsulate forwarded frames, with the blocks sent as the data portion of a UDP datagram. When the subscription starts, the TBU MUST send a Section Header Block followed by an Interface Description Block indicating a LinkType of LINKTYPE_IEEE802_15_4_NOFCS (230). Forwarded frames MUST be provided in Enhanced Packet Blocks. Only frames that are received by the device, have a valid FCS, have passed security, and are passed to upper layer are forwarded. Further, forwarded frames MUST be unencrypted, and MUST have the Auxiliary Security Header / Security Level field set to None (0).
    required:
    - subscriptionMode
    - fwdAddress
    - fwdPort
    properties:
      subscriptionMode:
        description: The listener starts or stops a frame subscription/forwarding. Start means start forwarding frames and Stop means cease forwarding frames. If the device implements /subscription/frames/hash, the device MUST maintain a SHA256 hash of all PCAPNG data forwarded between the acceptance of Start and Stop (inclusive), with this hash initialized to 0 upon reception of Start.
        type: string
        enum: [ Start, Stop ]
      fwdAddress:
        description: The IPv4 or IPv6 address of the listener. IPv6 address strings are formatted per RFC 5952.
        type: string
      fwdPort:
        description: The port number of the listener.
        type: integer

  UDPDatagram:
    type: object
    description: A UDP datagram to be sent from/to a specified source/destination address and port.
    required:
    - srcAddress
    - srcPort
    - destAddress
    - destPort
    - data
    - frameExchangePattern
    properties:
      srcAddress:
        description: The source address to be used by the sender. Must be one of the LL, ULA, GUA, or mcast addresses configured on the device. IPv6 address strings are formatted per RFC 5952.
        type: string
      srcPort:
        description: The port from which the datagram will be sent.
        type: integer
      destAddress:
        description: The destination address to which the datagram will be sent. IPv6 address strings are formatted per RFC 5952.
        type: string
      destPort:
        description: The port to which the datagram will be sent.
        type: integer
      data:
        description: The body of the UDP datagram encoded as a string of ASCII characters.
        type: string
      frameExchangePattern:
        description: Set to 0 if DFE is to be used, set to 1 if EDFE is to be used.
        type: integer
        enum: [0, 1]

  ICMPv6Echo:
    type: object
    description: An ICMPv6Echo message to be sent from/to a specified source/destination address. NOTE The response to this command should not wait for the Echo response. modeSwitch and phyModeID properties are optional FAN 1.1 additions.
    required:
      - srcAddress
      - destAddress
      - hopLimit
      - echoBody
      - frameExchangePattern
      - identifier
      - sequenceNumber
    properties:
      srcAddress:
        description: The source address to be used by the sender. Must be one of the LL, ULA, GUA, or mcast addresses configured on the device. IPv6 address strings are formatted per RFC 5952.
        type: string
      destAddress:
        description: The destination address to which the ICMPv6Echo message will be sent. IPv6 address strings are formatted per RFC 5952.
        type: string
      hopLimit:
        description: The hop limit value to be set in the IPv6 header.
        type: integer
      echoBody:
        description: The body of the ICMPv6Echo message encoded as a string of ASCII characters.
        type: string
      frameExchangePattern:
        description: Set to 0 if DFE is to be used, set to 1 if EDFE is to be used.
        type: integer
        enum: [0, 1]
      identifier:
        description: Value to be placed in the ICMPv6 Echo Identifier field.
        type: integer
        minimum: 0
        maximum: 65535
      sequenceNumber:
        description: Value to be placed in the ICMPv6 Echo Sequence Number field.
        type: integer
        minimum: 0
        maximum: 65535
      modeSwitch:
        description: 0 == do not attempt mode switch. 1 == the transmitter MUST attempt PHY mode switch. 2 == the transmitter MUST attempt MAC Command mode switch.
        type: integer
      phyModeID:
        description: The PhyModeID to which the device will attempt to switch. This value MUST be set to a PhyModeID value defined in section 5.2 of [PHYTPS].
        type: integer
      adjustedListeningOffset:
        description: The adjusted listening offset in milliseconds to send in an LTO-IE to an LFN destination.
        type: integer
      adjustedListeningInterval:
        description: The adjusted listening interval in milliseconds to send in an LTO-IE to an LFN destination.
        type: integer

  BorderRouterInformationElement:
    type: object
    description: Information element to be included within Border Router PC frame. Content field is omitted when the object is used with the DELETE method.
    required:
    - format
    - subID
    properties:
      format:
        description: 0 == header IE, 1 == short payload IE, 2 == long payload IE.
        type: integer
      subID:
        description: Set to WH-IE subID or WP-IE first nested subID (only one nested payload sub IE is supported).
        type: integer
      content:
        description: Arbitrary payload for the subID. Encoded as HEX string.
        type: string
        example: "000102030405060708090A0B0C0D0E0F"

  BorderRouterJoinMetric:
    type: object
    description: A Join Metric as used within the Join Metrics IE described in [FANTPS].
    required:
      - metricId
    properties:
      metricId:
        description: Set as specified in [FANTPS] JM-IE description.
        type: integer
      metricLength:
        description: Set as specified in [FANTPS] JM-IE description.
        type: integer
      metricData:
        description: Set as specified in [FANTPS] JM-IE description. Encoded as HEX string.
        type: string
        example: "000102030405060708090A0B0C0D0E0F"

  MulticastGroup:
    type: object
    description: A multicast group to be joined or left.
    required:
      - multicastAddress
    properties:
      multicastAddress:
        description: The multicast address to be joined or left. IPv6 address strings are formatted per RFC 5952.
        type: string
      multicastLifetime:
        description: 16-bit unsigned integer. The lifetime, in minutes, of the device's multicast group address registration. [RFC 6775 Section 4.1]
        type: integer
        default: 2160