rename set/get_output_power_levels to set/get_output_power as a higher patable setting does not necessarily imply a higher output power level (see table 39)

CHANGELOG.md

@@ -6,7 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
-- method `set/get_output_power_levels` to configure/retrieve output power settings
+- method `set/get_output_power` to configure/retrieve output power settings
   (`PATABLE` and `FREND0.PA_POWER`)
 
 ### Fixed

cc1101/__init__.py

@@ -643,9 +643,7 @@ class CC1101:
 
     def __str__(self) -> str:
         sync_mode = self.get_sync_mode()
-        output_power_levels_hex = tuple(
-            map("0x{:x}".format, self.get_output_power_levels())
-        )
+        output_power_settings_hex = tuple(map("0x{:x}".format, self.get_output_power()))
         attrs = (
             "marcstate={}".format(
                 self.get_main_radio_control_state_machine_state().name.lower()
@@ -668,10 +666,10 @@ class CC1101:
                 else "=",
                 self.get_packet_length_bytes(),
             ),
-            "output_power_levels=({})".format(
-                ",".join(output_power_levels_hex)
-                if len(output_power_levels_hex) > 1
-                else output_power_levels_hex[0] + ","
+            "output_power=({})".format(
+                ",".join(output_power_settings_hex)
+                if len(output_power_settings_hex) > 1
+                else output_power_settings_hex[0] + ","
             ),
         )
         return "CC1101({})".format(", ".join(filter(None, attrs)))
@@ -809,22 +807,22 @@ class CC1101:
             )
         )
 
-    def _set_patable(self, levels: typing.Iterable[int]):
-        levels = list(levels)
-        assert all(0 <= l <= 0xFF for l in levels), levels
-        assert 0 < len(levels) <= self._PATABLE_LENGTH_BYTES, levels
-        self._write_burst(start_register=PatableAddress.PATABLE, values=levels)
+    def _set_patable(self, settings: typing.Iterable[int]):
+        settings = list(settings)
+        assert all(0 <= l <= 0xFF for l in settings), settings
+        assert 0 < len(settings) <= self._PATABLE_LENGTH_BYTES, settings
+        self._write_burst(start_register=PatableAddress.PATABLE, values=settings)
 
-    def get_output_power_levels(self) -> typing.Tuple[int, ...]:
+    def get_output_power(self) -> typing.Tuple[int, ...]:
         """
-        Returns the enabled output power levels
+        Returns the enabled output power settings
         (up to 8 bytes of the PATABLE register).
 
-        see .set_output_power_levels()
+        see .set_output_power()
         """
         return self._get_patable()[: self._get_power_amplifier_setting_index() + 1]
 
-    def set_output_power_levels(self, power_levels: typing.Iterable[int]) -> None:
+    def set_output_power(self, power_settings: typing.Iterable[int]) -> None:
         """
         Configures output power levels by setting PATABLE and FREND0.PA_POWER.
         Up to 8 bytes may be provided.
@@ -836,15 +834,15 @@ class CC1101:
         For OOK modulation, exactly 2 bytes must be provided:
         0 to turn off the transmission for logical 0,
         and a level > 0 to turn on the transmission for logical 1.
-        >>> transceiver.set_output_power_levels((0, 0xC6))
+        >>> transceiver.set_output_power((0, 0xC6))
 
         See "Table 39: Optimum PATABLE Settings for Various Output Power Levels [...]"
         and section "24 Output Power Programming".
         """
-        power_levels = list(power_levels)
+        power_settings = list(power_settings)
         # checks in sub-methods
-        self._set_power_amplifier_setting_index(len(power_levels) - 1)
-        self._set_patable(power_levels)
+        self._set_power_amplifier_setting_index(len(power_settings) - 1)
+        self._set_patable(power_settings)
 
     def _flush_tx_fifo_buffer(self) -> None:
         # > Only issue SFTX in IDLE or TXFIFO_UNDERFLOW states.

examples/asynchronous_gpio_transmit.py

@@ -15,7 +15,7 @@ GPIO.setup(_GDO0_PIN, GPIO.OUT, initial=GPIO.LOW)
 with cc1101.CC1101() as transceiver:
     transceiver.set_base_frequency_hertz(433.92e6)
     transceiver.set_symbol_rate_baud(600)
-    transceiver.set_output_power_levels((0, 0xC0))  # OOK modulation: (off, on)
+    transceiver.set_output_power((0, 0xC0))  # OOK modulation: (off, on)
     print(transceiver)
     print("starting transmission")
     with transceiver.asynchronous_transmission():

examples/transmit_fixed_length.py

@@ -12,6 +12,6 @@ with cc1101.CC1101() as transceiver:
     transceiver.set_packet_length_mode(cc1101.PacketLengthMode.FIXED)
     transceiver.set_packet_length_bytes(4)
     transceiver.disable_checksum()
-    transceiver.set_output_power_levels((0, 0xC0))  # OOK modulation: (off, on)
+    transceiver.set_output_power((0, 0xC0))  # OOK modulation: (off, on)
     print(transceiver)
     transceiver.transmit(b"\xff\x00\xaa\xff")

examples/transmit_variable_length.py

@@ -14,7 +14,7 @@ with cc1101.CC1101(lock_spi_device=True) as transceiver:
     # transceiver.set_preamble_length_bytes(2)
     # transceiver.set_sync_word(b"\x12\x34")
     # transceiver.disable_checksum()
-    transceiver.set_output_power_levels((0, 0xC0))  # OOK modulation: (off, on)
+    transceiver.set_output_power((0, 0xC0))  # OOK modulation: (off, on)
     print(transceiver)
     print("state", transceiver.get_marc_state().name)
     print("base frequency", transceiver.get_base_frequency_hertz(), "Hz")
@@ -25,7 +25,7 @@ with cc1101.CC1101(lock_spi_device=True) as transceiver:
     if sync_mode != cc1101.SyncMode.NO_PREAMBLE_AND_SYNC_WORD:
         print("preamble length", transceiver.get_preamble_length_bytes(), "bytes")
         print("sync word", transceiver.get_sync_word())
-    print("output power level settings", transceiver.get_output_power_levels())
+    print("output power settings (patable)", transceiver.get_output_power())
     print("\nstarting transmission")
     transceiver.transmit(b"\xff\xaa\x00 message")
     time.sleep(1.0)

tests/test_config.py

@@ -167,13 +167,13 @@ def test_set_base_frequency_hertz_low_warning(transceiver, freq_hz, warn):
         ((0, 1, 2, 3, 4, 5, 21, 42), 7, (0, 1, 2, 3, 4, 5, 21, 42)),
     ),
 )
-def test_get_output_power_levels(transceiver, patable, patable_index, power_levels):
+def test_get_output_power(transceiver, patable, patable_index, power_levels):
     with unittest.mock.patch.object(
         transceiver, "_get_patable", return_value=patable
     ), unittest.mock.patch.object(
         transceiver, "_get_power_amplifier_setting_index", return_value=patable_index
     ):
-        assert transceiver.get_output_power_levels() == power_levels
+        assert transceiver.get_output_power() == power_levels
 
 
 @pytest.mark.parametrize(
@@ -186,13 +186,13 @@ def test_get_output_power_levels(transceiver, patable, patable_index, power_leve
         (7, (0, 1, 2, 3, 4, 5, 21, 42)),
     ),
 )
-def test_set_output_power_levels(transceiver, patable_index, power_levels):
+def test_set_output_power(transceiver, patable_index, power_levels):
     with unittest.mock.patch.object(
         transceiver, "_set_patable"
     ) as set_patable_mock, unittest.mock.patch.object(
         transceiver, "_set_power_amplifier_setting_index"
     ) as set_patable_index_mock:
-        transceiver.set_output_power_levels(power_levels)
+        transceiver.set_output_power(power_levels)
     set_patable_mock.assert_called_once_with(list(power_levels))
     set_patable_index_mock.assert_called_once_with(patable_index)
 
@@ -200,6 +200,6 @@ def test_set_output_power_levels(transceiver, patable_index, power_levels):
 @pytest.mark.parametrize(
     "power_levels", (tuple(), (21, 256), (0, 1, 2, 3, 4, 5, 6, 7, 8))
 )
-def test_set_output_power_levels_invalid(transceiver, power_levels):
+def test_set_output_power_invalid(transceiver, power_levels):
     with pytest.raises(Exception):
-        transceiver.set_output_power_levels(power_levels)
+        transceiver.set_output_power(power_levels)