dts/bindings/ieee802154/atmel,rf2xx.yaml

# Copyright (c) 2019-2020 Gerson Fernando Budke <nandojve@gmail.com>
# SPDX-License-Identifier: Apache-2.0

description: ATMEL AT86RF2xx 802.15.4 wireless transceiver

compatible: "atmel,rf2xx"

include: spi-device.yaml

properties:
    irq-gpios:
      type: phandle-array
      required: true

    reset-gpios:
      type: phandle-array
      required: true

    slptr-gpios:
      type: phandle-array
      required: true
      description: |
        Multi-functional pin that controls sleep, deep sleep, transmit
        start and receive states

    dig2-gpios:
      type: phandle-array
      required: false
      description: RX and TX Frame Time Stamping(TX_ARET)

    clkm-gpios:
      type: phandle-array
      required: false
      description: Master clock signal output

    local-mac-address:
      type: uint8-array
      description: |
        Specifies the MAC address that was assigned to the network
        device

    channel-page:
      type: int
      enum:
        - 0
        - 2
        - 5
      description: |
        Selects Channel Page accordingly with IEEE 802.15.4 standard. The Page 0
        is used in both Sub-Giga and 2.4GHz. It allows select channels 0-10 in
        Sub-Giga band (0: BPSK-20, 1-10: BPSK-40) and 11-26 in 2.4GHz band
        (11-26: O-QPSK-250). Channel 2 is for Sub-Giga and selects
        (0: OQPSK-SIN-RC-100, 1-10: OQPSK-SIN-250). Channel 5 is for Sub-Giga
        (JAPAN) and selects (0-3: OQPSK-RC-250) .
          0: Page 0 - BPSK-20 [0], BPSK-40 [1-10], O-QPSK-250 [11-26].
          2: Page 2 - OQPSK-SIN-RC-100 [0], OQPSK-SIN-250 [1-10].
          5: Page 5 - OQPSK-RC-250 [0-3].

    tx-pwr-table:
      type: uint8-array
      default: [ 0x00 ]
      description: |
        This is the Transmission Power Mapping Table array used to comply with
        local regulations. By default this value set an output power above 0dBm
        for all transceivers. This property must be used with tx-pwr-min and
        tx-pwr-max for normal operations. The number of elements is defined by
        the size of the tx-pwr-table array property. The max entry value for
        2.4GHz is 0x0f and 0xff for Sub-Giga. See PHY_TX_PWR at datasheet for
        more details.

        The output power is determined by following formula:

          linear_step = (tx-pwr-max - tx-pwr-min)
                      / (sizeof(tx-pwr-table) - 1.0);
          table_index = abs((value_in_dbm - tx-pwr-max) / linear_step);
          output_power = tx-pwr-table[table_index];

        Using AT86RF233 as example without external PA. By the datasheet the
        tx-pwr-min = -17 dBm and tx-pwr-max = +4 dBm. Using 48 elements in the
        tx-pwr-table array. The table array is filled from higher to lower power.

          tx-pwr-min = [01 11];	/* -17.0 dBm */
          tx-pwr-max = [00 04];	/*   4.0 dBm */
          tx-pwr-table = [00 01 03 04 05 05 06 06
                          07 07 07 08 08 09 09 0a
                          0a 0a 0b 0b 0b 0b 0c 0c
                          0c 0c 0d 0d 0d 0d 0d 0d
                          0d 0d 0e 0e 0e 0e 0e 0e
                          0e 0e 0e 0e 0e 0e 0f 0f];

        The values in the table are filled based on table 9-9 [ TX Output Power ]
        using the linear step in dBm as:

          linear_step = (4 - (-17)) / (48 - 1) => ~0.45 dBm

        Assuming that user wants set 0 dBm as output power:

          table_index = abs((0 - 4) / 0.45) => 8.95 ( round to 9 )
          output_power = tx-pwr-table[9] => 0x07 ( 0 dBm as table 9-9 )

        Note when tx-pwr-min is [ 0x00, 0x00 ] and tx-pwr-max is [ 0x00, 0x00 ]
        the linear step is zero. This means that table_index will be always the
        first element of the tx-pwr-table array, which is 0x00 by default. This
        is defined as general case when user not define any tx-pwr-* entries. It
        sets the transceiver to use always a value above 0 dBm as output power.

    tx-pwr-min:
      type: uint8-array
      default: [ 0x00, 0x00 ]
      description: |
        This value represent minimum normalized value in dBm for the transceiver
        output power. This property must be used when tx-pwr-table is defined.
        The value is represented by two entries where first element represents
        the signal indication [ 0x00-positive, 0x01-negative] and second element
        is the minimal value in dBm for the transceiver output power. By default,
        the combination of tx-pwr-min as [ 0x00, 0x00 ] and tx-pwr-max as [ 0x00,
        0x00 ] will create a fixed transmission power.

    tx-pwr-max:
      type: uint8-array
      default: [ 0x00, 0x00 ]
      description: |
        This value represent maximum normalized value in dBm for the transceiver
        output power. This property must be used when tx-pwr-table is defined.
        The value is represented by two entries where first element represents
        the signal indication [ 0x00-positive ] and second element is the maximum
        value in dBm for the transceiver output power. By default, the
        combination of tx-pwr-max as [ 0x00, 0x00 ] and tx-pwr-min as [ 0x00,
        0x00 ] will create a fixed transmission power.