__init__.py 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973
  1. # python-cc1101 - Python Library to Transmit RF Signals via CC1101 Transceivers
  2. #
  3. # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
  4. #
  5. # This program is free software: you can redistribute it and/or modify
  6. # it under the terms of the GNU General Public License as published by
  7. # the Free Software Foundation, either version 3 of the License, or
  8. # any later version.
  9. #
  10. # This program is distributed in the hope that it will be useful,
  11. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. # GNU General Public License for more details.
  14. #
  15. # You should have received a copy of the GNU General Public License
  16. # along with this program. If not, see <https://www.gnu.org/licenses/>.
  17. from __future__ import annotations
  18. import contextlib
  19. import datetime
  20. import enum
  21. import fcntl
  22. import logging
  23. import math
  24. import typing
  25. import warnings
  26. import spidev
  27. import cc1101._gpio
  28. from cc1101.addresses import (
  29. ConfigurationRegisterAddress,
  30. FIFORegisterAddress,
  31. PatableAddress,
  32. StatusRegisterAddress,
  33. StrobeAddress,
  34. )
  35. from cc1101.options import (
  36. GDOSignalSelection,
  37. ModulationFormat,
  38. PacketLengthMode,
  39. SyncMode,
  40. _TransceiveMode,
  41. )
  42. _LOGGER = logging.getLogger(__name__)
  43. class Pin(enum.Enum):
  44. GDO0 = "GDO0"
  45. class MainRadioControlStateMachineState(enum.IntEnum):
  46. """
  47. MARCSTATE - Main Radio Control State Machine State
  48. """
  49. # see "Figure 13: Simplified State Diagram"
  50. # and "Figure 25: Complete Radio Control State Diagram"
  51. IDLE = 0x01
  52. STARTCAL = 0x08 # after IDLE
  53. BWBOOST = 0x09 # after STARTCAL
  54. FS_LOCK = 0x0A
  55. RX = 0x0D
  56. RXFIFO_OVERFLOW = 0x11
  57. TX = 0x13
  58. # TXFIFO_UNDERFLOW = 0x16
  59. class _ReceivedPacket: # unstable
  60. # "Table 31: Typical RSSI_offset Values"
  61. _RSSI_OFFSET_dB = 74
  62. def __init__(
  63. self,
  64. *,
  65. payload: bytes,
  66. rssi_index: int, # byte
  67. checksum_valid: bool,
  68. link_quality_indicator: int, # 7bit
  69. ):
  70. self.payload = payload
  71. self._rssi_index = rssi_index
  72. assert 0 <= rssi_index < (1 << 8), rssi_index
  73. self.checksum_valid = checksum_valid
  74. self.link_quality_indicator = link_quality_indicator
  75. assert 0 <= link_quality_indicator < (1 << 7), link_quality_indicator
  76. @property
  77. def rssi_dbm(self) -> float:
  78. """
  79. Estimated Received Signal Strength Indicator (RSSI) in dBm
  80. see section "17.3 RSSI"
  81. """
  82. if self._rssi_index >= 128:
  83. return (self._rssi_index - 256) / 2 - self._RSSI_OFFSET_dB
  84. return self._rssi_index / 2 - self._RSSI_OFFSET_dB
  85. def __str__(self) -> str:
  86. return f"{type(self).__name__}(RSSI {self.rssi_dbm:.0f}dBm, 0x{self.payload.hex()})"
  87. def _format_patable(settings: typing.Iterable[int], insert_spaces: bool) -> str:
  88. # "Table 39: Optimum PATABLE Settings" uses hexadecimal digits
  89. # "0" for brevity
  90. settings_hex = tuple(map(lambda s: "0" if s == 0 else f"0x{s:x}", settings))
  91. if len(settings_hex) == 1:
  92. return f"({settings_hex[0]},)"
  93. delimiter = ", " if insert_spaces else ","
  94. return f"({delimiter.join(settings_hex)})"
  95. class CC1101:
  96. # pylint: disable=too-many-public-methods
  97. # > All transfers on the SPI interface are done
  98. # > most significant bit first.
  99. # > All transactions on the SPI interface start with
  100. # > a header byte containing a R/W bit, a access bit (B),
  101. # > and a 6-bit address (A5 - A0).
  102. # > [...]
  103. # > Table 45: SPI Address Space
  104. _WRITE_SINGLE_BYTE = 0x00
  105. # > Registers with consecutive addresses can be
  106. # > accessed in an efficient way by setting the
  107. # > burst bit (B) in the header byte. The address
  108. # > bits (A5 - A0) set the start address in an
  109. # > internal address counter. This counter is
  110. # > incremented by one each new byte [...]
  111. _WRITE_BURST = 0x40
  112. _READ_SINGLE_BYTE = 0x80
  113. _READ_BURST = 0xC0
  114. # 29.3 Status Register Details
  115. _SUPPORTED_PARTNUM = 0
  116. # > The two versions of the chip will behave the same.
  117. # https://e2e.ti.com/support/wireless-connectivity/sub-1-ghz/f/156/p/428028/1529544#1529544
  118. _SUPPORTED_VERSIONS = [
  119. 0x04, # https://github.com/fphammerle/python-cc1101/issues/15
  120. 0x14,
  121. ]
  122. _CRYSTAL_OSCILLATOR_FREQUENCY_HERTZ = 26e6
  123. # see "21 Frequency Programming"
  124. # > f_carrier = f_XOSC / 2**16 * (FREQ + CHAN * ((256 + CHANSPC_M) * 2**CHANSPC_E-2))
  125. _FREQUENCY_CONTROL_WORD_HERTZ_FACTOR = _CRYSTAL_OSCILLATOR_FREQUENCY_HERTZ / 2 ** 16
  126. # roughly estimated / tested with SDR receiver, docs specify:
  127. # > can [...] be programmed for operation at other frequencies
  128. # > in the 300-348 MHz, 387-464 MHz and 779-928 MHz bands.
  129. _TRANSMIT_MIN_FREQUENCY_HERTZ = 281.7e6
  130. # > The PATABLE is an 8-byte table that defines the PA control settings [...]
  131. _PATABLE_LENGTH_BYTES = 8
  132. def __init__(
  133. self, spi_bus: int = 0, spi_chip_select: int = 0, lock_spi_device: bool = False
  134. ) -> None:
  135. """
  136. lock_spi_device:
  137. When True, an advisory, exclusive lock will be set on the SPI device file
  138. non-blockingly via flock upon entering the context.
  139. If the SPI device file is already locked (e.g., by a different process),
  140. a BlockingIOError will be raised.
  141. The lock will be removed automatically, when leaving the context.
  142. The lock can optionally be released earlier by calling .unlock_spi_device().
  143. >>> transceiver = cc1101.CC1101(lock_spi_device=True)
  144. >>> # not locked
  145. >>> with transceiver:
  146. >>> # locked
  147. >>> # lock removed
  148. >>> with transceiver:
  149. >>> # locked
  150. >>> transceiver.unlock_spi_device()
  151. >>> # lock removed
  152. """
  153. self._spi = spidev.SpiDev()
  154. self._spi_bus = int(spi_bus)
  155. # > The BCM2835 core common to all Raspberry Pi devices has 3 SPI Controllers:
  156. # > SPI0, with two hardware chip selects, [...]
  157. # > SPI1, with three hardware chip selects, [...]
  158. # > SPI2, also with three hardware chip selects, is only usable on a Compute Module [...]
  159. # https://github.com/raspberrypi/documentation/blob/d41d69f8efa3667b1a8b01a669238b8bd113edc1/hardware/raspberrypi/spi/README.md#hardware
  160. # https://www.raspberrypi.org/documentation/hardware/raspberrypi/spi/README.md
  161. self._spi_chip_select = int(spi_chip_select)
  162. self._lock_spi_device = lock_spi_device
  163. @property
  164. def _spi_device_path(self) -> str:
  165. # https://github.com/doceme/py-spidev/blob/v3.4/spidev_module.c#L1286
  166. return f"/dev/spidev{self._spi_bus}.{self._spi_chip_select}"
  167. @staticmethod
  168. def _log_chip_status_byte(chip_status: int) -> None:
  169. # see "10.1 Chip Status Byte" & "Table 23: Status Byte Summary"
  170. # > The command strobe registers are accessed by transferring
  171. # > a single header byte [...]. That is, only the R/W̄ bit,
  172. # > the burst access bit (set to 0), and the six address bits [...]
  173. # > The R/W̄ bit can be either one or zero and will determine how the
  174. # > FIFO_BYTES_AVAILABLE field in the status byte should be interpreted.
  175. _LOGGER.debug(
  176. "chip status byte: CHIP_RDYn=%d STATE=%s FIFO_BYTES_AVAILBLE=%d",
  177. chip_status >> 7,
  178. bin((chip_status >> 4) & 0b111),
  179. chip_status & 0b1111,
  180. )
  181. def _read_single_byte(
  182. self, register: typing.Union[ConfigurationRegisterAddress, FIFORegisterAddress]
  183. ) -> int:
  184. response = self._spi.xfer([register | self._READ_SINGLE_BYTE, 0])
  185. assert len(response) == 2, response
  186. self._log_chip_status_byte(response[0])
  187. return response[1]
  188. def _read_burst(
  189. self,
  190. start_register: typing.Union[
  191. ConfigurationRegisterAddress, PatableAddress, FIFORegisterAddress
  192. ],
  193. length: int,
  194. ) -> typing.List[int]:
  195. response = self._spi.xfer([start_register | self._READ_BURST] + [0] * length)
  196. assert len(response) == length + 1, response
  197. self._log_chip_status_byte(response[0])
  198. return response[1:]
  199. def _read_status_register(self, register: StatusRegisterAddress) -> int:
  200. # > For register addresses in the range 0x30-0x3D,
  201. # > the burst bit is used to select between
  202. # > status registers when burst bit is one, and
  203. # > between command strobes when burst bit is
  204. # > zero. [...]
  205. # > Because of this, burst access is not available
  206. # > for status registers and they must be accessed
  207. # > one at a time. The status registers can only be
  208. # > read.
  209. response = self._spi.xfer([register | self._READ_BURST, 0])
  210. assert len(response) == 2, response
  211. self._log_chip_status_byte(response[0])
  212. return response[1]
  213. def _command_strobe(self, register: StrobeAddress) -> None:
  214. # see "10.4 Command Strobes"
  215. _LOGGER.debug("sending command strobe 0x%02x", register)
  216. response = self._spi.xfer([register | self._WRITE_SINGLE_BYTE])
  217. assert len(response) == 1, response
  218. self._log_chip_status_byte(response[0])
  219. def _write_burst(
  220. self,
  221. start_register: typing.Union[
  222. ConfigurationRegisterAddress, PatableAddress, FIFORegisterAddress
  223. ],
  224. values: typing.List[int],
  225. ) -> None:
  226. _LOGGER.debug(
  227. "writing burst: start_register=0x%02x values=%s", start_register, values
  228. )
  229. response = self._spi.xfer([start_register | self._WRITE_BURST] + values)
  230. assert len(response) == len(values) + 1, response
  231. self._log_chip_status_byte(response[0])
  232. assert all(v == response[0] for v in response[1:]), response
  233. def _reset(self) -> None:
  234. self._command_strobe(StrobeAddress.SRES)
  235. @classmethod
  236. def _filter_bandwidth_floating_point_to_real(
  237. cls, *, mantissa: int, exponent: int
  238. ) -> float:
  239. """
  240. See "13 Receiver Channel Filter Bandwidth"
  241. """
  242. return cls._CRYSTAL_OSCILLATOR_FREQUENCY_HERTZ / (
  243. 8 * (4 + mantissa) * (2 ** exponent)
  244. )
  245. def _get_filter_bandwidth_hertz(self) -> float:
  246. """
  247. MDMCFG4.CHANBW_E & MDMCFG4.CHANBW_M
  248. > [...] decimation ratio for the delta-sigma ADC input stream
  249. > and thus the channel bandwidth.
  250. See "13 Receiver Channel Filter Bandwidth"
  251. """
  252. mdmcfg4 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG4)
  253. return self._filter_bandwidth_floating_point_to_real(
  254. exponent=mdmcfg4 >> 6, mantissa=(mdmcfg4 >> 4) & 0b11
  255. )
  256. def _set_filter_bandwidth(self, *, mantissa: int, exponent: int) -> None:
  257. """
  258. MDMCFG4.CHANBW_E & MDMCFG4.CHANBW_M
  259. """
  260. mdmcfg4 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG4)
  261. mdmcfg4 &= 0b00001111
  262. assert 0 <= exponent <= 0b11, exponent
  263. mdmcfg4 |= exponent << 6
  264. assert 0 <= mantissa <= 0b11, mantissa
  265. mdmcfg4 |= mantissa << 4
  266. self._write_burst(
  267. start_register=ConfigurationRegisterAddress.MDMCFG4, values=[mdmcfg4]
  268. )
  269. def _get_symbol_rate_exponent(self) -> int:
  270. """
  271. MDMCFG4.DRATE_E
  272. """
  273. return self._read_single_byte(ConfigurationRegisterAddress.MDMCFG4) & 0b00001111
  274. def _set_symbol_rate_exponent(self, exponent: int):
  275. mdmcfg4 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG4)
  276. mdmcfg4 &= 0b11110000
  277. mdmcfg4 |= exponent
  278. self._write_burst(
  279. start_register=ConfigurationRegisterAddress.MDMCFG4, values=[mdmcfg4]
  280. )
  281. def _get_symbol_rate_mantissa(self) -> int:
  282. """
  283. MDMCFG3.DRATE_M
  284. """
  285. return self._read_single_byte(ConfigurationRegisterAddress.MDMCFG3)
  286. def _set_symbol_rate_mantissa(self, mantissa: int) -> None:
  287. self._write_burst(
  288. start_register=ConfigurationRegisterAddress.MDMCFG3, values=[mantissa]
  289. )
  290. @classmethod
  291. def _symbol_rate_floating_point_to_real(
  292. cls, *, mantissa: int, exponent: int
  293. ) -> float:
  294. # see "12 Data Rate Programming"
  295. return (
  296. (256 + mantissa)
  297. * (2 ** exponent)
  298. * cls._CRYSTAL_OSCILLATOR_FREQUENCY_HERTZ
  299. / (2 ** 28)
  300. )
  301. @classmethod
  302. def _symbol_rate_real_to_floating_point(cls, real: float) -> typing.Tuple[int, int]:
  303. # see "12 Data Rate Programming"
  304. assert real > 0, real
  305. exponent = math.floor(
  306. math.log2(real / cls._CRYSTAL_OSCILLATOR_FREQUENCY_HERTZ) + 20
  307. )
  308. mantissa = round(
  309. real * 2 ** 28 / cls._CRYSTAL_OSCILLATOR_FREQUENCY_HERTZ / 2 ** exponent
  310. - 256
  311. )
  312. if mantissa == 256:
  313. exponent += 1
  314. mantissa = 0
  315. assert 0 < exponent <= 2 ** 4, exponent
  316. assert mantissa <= 2 ** 8, mantissa
  317. return mantissa, exponent
  318. def get_symbol_rate_baud(self) -> float:
  319. return self._symbol_rate_floating_point_to_real(
  320. mantissa=self._get_symbol_rate_mantissa(),
  321. exponent=self._get_symbol_rate_exponent(),
  322. )
  323. def set_symbol_rate_baud(self, real: float) -> None:
  324. # > The data rate can be set from 0.6 kBaud to 500 kBaud [...]
  325. mantissa, exponent = self._symbol_rate_real_to_floating_point(real)
  326. self._set_symbol_rate_mantissa(mantissa)
  327. self._set_symbol_rate_exponent(exponent)
  328. def get_modulation_format(self) -> ModulationFormat:
  329. mdmcfg2 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG2)
  330. return ModulationFormat((mdmcfg2 >> 4) & 0b111)
  331. def _set_modulation_format(self, modulation_format: ModulationFormat) -> None:
  332. mdmcfg2 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG2)
  333. mdmcfg2 &= 0b10001111
  334. mdmcfg2 |= modulation_format << 4
  335. self._write_burst(ConfigurationRegisterAddress.MDMCFG2, [mdmcfg2])
  336. def enable_manchester_code(self) -> None:
  337. """
  338. MDMCFG2.MANCHESTER_EN
  339. Enable manchester encoding & decoding for the entire packet,
  340. including the preamble and synchronization word.
  341. """
  342. mdmcfg2 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG2)
  343. mdmcfg2 |= 0b1000
  344. self._write_burst(ConfigurationRegisterAddress.MDMCFG2, [mdmcfg2])
  345. def get_sync_mode(self) -> SyncMode:
  346. mdmcfg2 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG2)
  347. return SyncMode(mdmcfg2 & 0b11)
  348. def set_sync_mode(
  349. self,
  350. mode: SyncMode,
  351. *,
  352. _carrier_sense_threshold_enabled: typing.Optional[bool] = None, # unstable
  353. ) -> None:
  354. """
  355. MDMCFG2.SYNC_MODE
  356. see "14.3 Byte Synchronization"
  357. Carrier Sense (CS) Threshold (when receiving packets, API unstable):
  358. > Carrier sense can be used as a sync word qualifier
  359. > that requires the signal level to be higher than the threshold
  360. > for a sync word > search to be performed [...]
  361. > CS can be used to avoid interference from other RF sources [...]
  362. True: enable, False: disable, None: keep current setting
  363. See "17.4 Carrier Sense (CS)"
  364. """
  365. mdmcfg2 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG2)
  366. mdmcfg2 &= 0b11111100
  367. mdmcfg2 |= mode
  368. if _carrier_sense_threshold_enabled is not None:
  369. if _carrier_sense_threshold_enabled:
  370. mdmcfg2 |= 0b00000100
  371. else:
  372. mdmcfg2 &= 0b11111011
  373. self._write_burst(ConfigurationRegisterAddress.MDMCFG2, [mdmcfg2])
  374. def get_preamble_length_bytes(self) -> int:
  375. """
  376. MDMCFG1.NUM_PREAMBLE
  377. Minimum number of preamble bytes to be transmitted.
  378. See "15.2 Packet Format"
  379. """
  380. index = (
  381. self._read_single_byte(ConfigurationRegisterAddress.MDMCFG1) >> 4
  382. ) & 0b111
  383. return 2 ** (index >> 1) * (2 + (index & 0b1))
  384. def _set_preamble_length_index(self, index: int) -> None:
  385. assert 0 <= index <= 0b111
  386. mdmcfg1 = self._read_single_byte(ConfigurationRegisterAddress.MDMCFG1)
  387. mdmcfg1 &= 0b10001111
  388. mdmcfg1 |= index << 4
  389. self._write_burst(ConfigurationRegisterAddress.MDMCFG1, [mdmcfg1])
  390. def set_preamble_length_bytes(self, length: int) -> None:
  391. """
  392. see .get_preamble_length_bytes()
  393. """
  394. if length < 1:
  395. raise ValueError(
  396. f"invalid preamble length {length} given"
  397. "\ncall .set_sync_mode(cc1101.SyncMode.NO_PREAMBLE_AND_SYNC_WORD)"
  398. " to disable preamble"
  399. )
  400. if length % 3 == 0:
  401. index = math.log2(length / 3) * 2 + 1
  402. else:
  403. index = math.log2(length / 2) * 2
  404. if not index.is_integer() or index < 0 or index > 0b111:
  405. raise ValueError(
  406. f"unsupported preamble length: {length} bytes"
  407. "\nsee MDMCFG1.NUM_PREAMBLE in cc1101 docs"
  408. )
  409. self._set_preamble_length_index(int(index))
  410. def _get_power_amplifier_setting_index(self) -> int:
  411. """
  412. see ._set_power_amplifier_setting_index
  413. """
  414. return self._read_single_byte(ConfigurationRegisterAddress.FREND0) & 0b111
  415. def _set_power_amplifier_setting_index(self, setting_index: int) -> None:
  416. """
  417. FREND0.PA_POWER
  418. > This value is an index to the PATABLE,
  419. > which can be programmed with up to 8 different PA settings.
  420. > In OOK/ASK mode, this selects the PATABLE index to use
  421. > when transmitting a '1'.
  422. > PATABLE index zero is used in OOK/ASK when transmitting a '0'.
  423. > The PATABLE settings from index 0 to the PA_POWER value are
  424. > used for > ASK TX shaping, [...]
  425. see "Figure 32: Shaping of ASK Signal"
  426. > If OOK modulation is used, the logic 0 and logic 1 power levels
  427. > shall be programmed to index 0 and 1 respectively.
  428. """
  429. assert 0 <= setting_index <= 0b111, setting_index
  430. frend0 = self._read_single_byte(ConfigurationRegisterAddress.FREND0)
  431. frend0 &= 0b11111000
  432. frend0 |= setting_index
  433. self._write_burst(ConfigurationRegisterAddress.FREND0, [frend0])
  434. def _verify_chip(self) -> None:
  435. partnum = self._read_status_register(StatusRegisterAddress.PARTNUM)
  436. if partnum != self._SUPPORTED_PARTNUM:
  437. raise ValueError(
  438. f"unexpected chip part number {partnum} (expected: {self._SUPPORTED_PARTNUM})"
  439. )
  440. version = self._read_status_register(StatusRegisterAddress.VERSION)
  441. if version not in self._SUPPORTED_VERSIONS:
  442. msg = f"Unsupported chip version 0x{version:02x}"
  443. supported_versions = ", ".join(
  444. f"0x{v:02x}" for v in self._SUPPORTED_VERSIONS
  445. )
  446. msg += f" (expected one of [{supported_versions}])"
  447. if version == 0:
  448. msg += (
  449. "\n\nPlease verify that all required pins are connected"
  450. " (see https://github.com/fphammerle/python-cc1101#wiring-raspberry-pi)"
  451. " and that you selected the correct SPI bus and chip/slave select line."
  452. )
  453. raise ValueError(msg)
  454. def _configure_defaults(self) -> None:
  455. # next major/breaking release will probably stick closer to CC1101's defaults
  456. # 6:4 MOD_FORMAT: OOK (default: 2-FSK)
  457. self._set_modulation_format(ModulationFormat.ASK_OOK)
  458. self._set_power_amplifier_setting_index(1)
  459. self._disable_data_whitening()
  460. # 7:6 unused
  461. # 5:4 FS_AUTOCAL: calibrate when going from IDLE to RX or TX
  462. # 3:2 PO_TIMEOUT: default
  463. # 1 PIN_CTRL_EN: default
  464. # 0 XOSC_FORCE_ON: default
  465. self._write_burst(ConfigurationRegisterAddress.MCSM0, [0b010100])
  466. # > Default is CLK_XOSC/192 (See Table 41 on page 62).
  467. # > It is recommended to disable the clock output in initialization,
  468. # > in order to optimize RF performance.
  469. self._write_burst(
  470. ConfigurationRegisterAddress.IOCFG0,
  471. # required for _wait_for_packet()
  472. [GDOSignalSelection.RX_FIFO_AT_OR_ABOVE_THRESHOLD_OR_PACKET_END_REACHED],
  473. )
  474. def __enter__(self) -> CC1101:
  475. # https://docs.python.org/3/reference/datamodel.html#object.__enter__
  476. try:
  477. self._spi.open(self._spi_bus, self._spi_chip_select)
  478. except PermissionError as exc:
  479. raise PermissionError(
  480. f"Could not access {self._spi_device_path}"
  481. "\nVerify that the current user has both read and write access."
  482. "\nOn some systems, like Raspberry Pi OS / Raspbian,"
  483. "\n\tsudo usermod -a -G spi $USER"
  484. "\nfollowed by a re-login grants sufficient permissions."
  485. ) from exc
  486. if self._lock_spi_device:
  487. # advisory, exclusive, non-blocking
  488. # lock removed in __exit__ by SpiDev.close()
  489. fcntl.flock(self._spi.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
  490. try:
  491. self._spi.max_speed_hz = 55700 # empirical
  492. self._reset()
  493. self._verify_chip()
  494. self._configure_defaults()
  495. marcstate = self.get_main_radio_control_state_machine_state()
  496. if marcstate != MainRadioControlStateMachineState.IDLE:
  497. raise ValueError(f"expected marcstate idle (actual: {marcstate.name})")
  498. except:
  499. self._spi.close()
  500. raise
  501. return self
  502. def __exit__(self, exc_type, exc_value, traceback): # -> typing.Literal[False]
  503. # https://docs.python.org/3/reference/datamodel.html#object.__exit__
  504. self._spi.close()
  505. return False
  506. def unlock_spi_device(self) -> None:
  507. """
  508. Manually release the lock set on the SPI device file.
  509. Alternatively, the lock will be released automatically,
  510. when leaving the context.
  511. Method fails silently, if the SPI device file is not locked.
  512. >>> transceiver = cc1101.CC1101(lock_spi_device=True)
  513. >>> # not locked
  514. >>> with transceiver:
  515. >>> # locked
  516. >>> # lock removed
  517. >>> with transceiver:
  518. >>> # locked
  519. >>> transceiver.unlock_spi_device()
  520. >>> # lock removed
  521. """
  522. fileno = self._spi.fileno()
  523. if fileno != -1:
  524. fcntl.flock(fileno, fcntl.LOCK_UN)
  525. def get_main_radio_control_state_machine_state(
  526. self,
  527. ) -> MainRadioControlStateMachineState:
  528. return MainRadioControlStateMachineState(
  529. self._read_status_register(StatusRegisterAddress.MARCSTATE)
  530. )
  531. def get_marc_state(self) -> MainRadioControlStateMachineState:
  532. """
  533. alias for get_main_radio_control_state_machine_state()
  534. """
  535. return self.get_main_radio_control_state_machine_state()
  536. @classmethod
  537. def _frequency_control_word_to_hertz(cls, control_word: typing.List[int]) -> float:
  538. return (
  539. int.from_bytes(control_word, byteorder="big", signed=False)
  540. * cls._FREQUENCY_CONTROL_WORD_HERTZ_FACTOR
  541. )
  542. @classmethod
  543. def _hertz_to_frequency_control_word(cls, hertz: float) -> typing.List[int]:
  544. return list(
  545. round(hertz / cls._FREQUENCY_CONTROL_WORD_HERTZ_FACTOR).to_bytes(
  546. length=3, byteorder="big", signed=False
  547. )
  548. )
  549. def _get_base_frequency_control_word(self) -> typing.List[int]:
  550. # > The base or start frequency is set by the 24 bitfrequency
  551. # > word located in the FREQ2, FREQ1, FREQ0 registers.
  552. return self._read_burst(
  553. start_register=ConfigurationRegisterAddress.FREQ2, length=3
  554. )
  555. def _set_base_frequency_control_word(self, control_word: typing.List[int]) -> None:
  556. self._write_burst(
  557. start_register=ConfigurationRegisterAddress.FREQ2, values=control_word
  558. )
  559. def get_base_frequency_hertz(self) -> float:
  560. return self._frequency_control_word_to_hertz(
  561. self._get_base_frequency_control_word()
  562. )
  563. def set_base_frequency_hertz(self, freq: float) -> None:
  564. if freq < (self._TRANSMIT_MIN_FREQUENCY_HERTZ - 50e3):
  565. # > [use] warnings.warn() in library code if the issue is avoidable
  566. # > and the client application should be modified to eliminate the warning[.]
  567. # > [use] logging.warning() if there is nothing the client application
  568. # > can do about the situation, but the event should still be noted.
  569. # https://docs.python.org/3/howto/logging.html#when-to-use-logging
  570. warnings.warn(
  571. "CC1101 is unable to transmit at frequencies"
  572. f" below {(self._TRANSMIT_MIN_FREQUENCY_HERTZ / 1e6):.1f} MHz"
  573. )
  574. self._set_base_frequency_control_word(
  575. self._hertz_to_frequency_control_word(freq)
  576. )
  577. def __str__(self) -> str:
  578. sync_mode = self.get_sync_mode()
  579. attrs = (
  580. f"marcstate={self.get_main_radio_control_state_machine_state().name.lower()}",
  581. f"base_frequency={(self.get_base_frequency_hertz() / 1e6):.2f}MHz",
  582. f"symbol_rate={(self.get_symbol_rate_baud() / 1000):.2f}kBaud",
  583. f"modulation_format={self.get_modulation_format().name}",
  584. f"sync_mode={sync_mode.name}",
  585. f"preamble_length={self.get_preamble_length_bytes()}B"
  586. if sync_mode != SyncMode.NO_PREAMBLE_AND_SYNC_WORD
  587. else None,
  588. f"sync_word=0x{self.get_sync_word().hex()}"
  589. if sync_mode != SyncMode.NO_PREAMBLE_AND_SYNC_WORD
  590. else None,
  591. "packet_length{}{}B".format( # pylint: disable=consider-using-f-string
  592. "≤"
  593. if self.get_packet_length_mode() == PacketLengthMode.VARIABLE
  594. else "=",
  595. self.get_packet_length_bytes(),
  596. ),
  597. "output_power="
  598. + _format_patable(self.get_output_power(), insert_spaces=False),
  599. )
  600. # pylint: disable=consider-using-f-string
  601. return "CC1101({})".format(", ".join(filter(None, attrs)))
  602. def get_configuration_register_values(
  603. self,
  604. start_register: ConfigurationRegisterAddress = min(
  605. ConfigurationRegisterAddress
  606. ),
  607. end_register: ConfigurationRegisterAddress = max(ConfigurationRegisterAddress),
  608. ) -> typing.Dict[ConfigurationRegisterAddress, int]:
  609. assert start_register <= end_register, (start_register, end_register)
  610. values = self._read_burst(
  611. start_register=start_register, length=end_register - start_register + 1
  612. )
  613. return {
  614. ConfigurationRegisterAddress(start_register + i): v
  615. for i, v in enumerate(values)
  616. }
  617. def get_sync_word(self) -> bytes:
  618. """
  619. SYNC1 & SYNC0
  620. See "15.2 Packet Format"
  621. The first byte's most significant bit is transmitted first.
  622. """
  623. return bytes(
  624. self._read_burst(
  625. start_register=ConfigurationRegisterAddress.SYNC1, length=2
  626. )
  627. )
  628. def set_sync_word(self, sync_word: bytes) -> None:
  629. """
  630. See .set_sync_word()
  631. """
  632. if len(sync_word) != 2:
  633. raise ValueError(f"expected two bytes, got {sync_word!r}")
  634. self._write_burst(
  635. start_register=ConfigurationRegisterAddress.SYNC1, values=list(sync_word)
  636. )
  637. def get_packet_length_bytes(self) -> int:
  638. """
  639. PKTLEN
  640. Packet length in fixed packet length mode,
  641. maximum packet length in variable packet length mode.
  642. > In variable packet length mode, [...]
  643. > any packet received with a length byte
  644. > with a value greater than PKTLEN will be discarded.
  645. """
  646. return self._read_single_byte(ConfigurationRegisterAddress.PKTLEN)
  647. def set_packet_length_bytes(self, packet_length: int) -> None:
  648. """
  649. see get_packet_length_bytes()
  650. """
  651. assert 1 <= packet_length <= 255, f"unsupported packet length {packet_length}"
  652. self._write_burst(
  653. start_register=ConfigurationRegisterAddress.PKTLEN, values=[packet_length]
  654. )
  655. def _disable_data_whitening(self):
  656. """
  657. PKTCTRL0.WHITE_DATA
  658. see "15.1 Data Whitening"
  659. > By setting PKTCTRL0.WHITE_DATA=1 [default],
  660. > all data, except the preamble and the sync word
  661. > will be XOR-ed with a 9-bit pseudo-random (PN9)
  662. > sequence before being transmitted.
  663. """
  664. pktctrl0 = self._read_single_byte(ConfigurationRegisterAddress.PKTCTRL0)
  665. pktctrl0 &= 0b10111111
  666. self._write_burst(
  667. start_register=ConfigurationRegisterAddress.PKTCTRL0, values=[pktctrl0]
  668. )
  669. def disable_checksum(self) -> None:
  670. """
  671. PKTCTRL0.CRC_EN
  672. Disable automatic 2-byte cyclic redundancy check (CRC) sum
  673. appending in TX mode and checking in RX mode.
  674. See "Figure 19: Packet Format".
  675. """
  676. pktctrl0 = self._read_single_byte(ConfigurationRegisterAddress.PKTCTRL0)
  677. pktctrl0 &= 0b11111011
  678. self._write_burst(
  679. start_register=ConfigurationRegisterAddress.PKTCTRL0, values=[pktctrl0]
  680. )
  681. def _get_transceive_mode(self) -> _TransceiveMode:
  682. pktctrl0 = self._read_single_byte(ConfigurationRegisterAddress.PKTCTRL0)
  683. return _TransceiveMode((pktctrl0 >> 4) & 0b11)
  684. def _set_transceive_mode(self, mode: _TransceiveMode) -> None:
  685. _LOGGER.info("changing transceive mode to %s", mode.name)
  686. pktctrl0 = self._read_single_byte(ConfigurationRegisterAddress.PKTCTRL0)
  687. pktctrl0 &= ~0b00110000
  688. pktctrl0 |= mode << 4
  689. self._write_burst(
  690. start_register=ConfigurationRegisterAddress.PKTCTRL0, values=[pktctrl0]
  691. )
  692. def get_packet_length_mode(self) -> PacketLengthMode:
  693. pktctrl0 = self._read_single_byte(ConfigurationRegisterAddress.PKTCTRL0)
  694. return PacketLengthMode(pktctrl0 & 0b11)
  695. def set_packet_length_mode(self, mode: PacketLengthMode) -> None:
  696. pktctrl0 = self._read_single_byte(ConfigurationRegisterAddress.PKTCTRL0)
  697. pktctrl0 &= 0b11111100
  698. pktctrl0 |= mode
  699. self._write_burst(
  700. start_register=ConfigurationRegisterAddress.PKTCTRL0, values=[pktctrl0]
  701. )
  702. def _get_patable(self) -> typing.Tuple[int, ...]:
  703. """
  704. see "10.6 PATABLE Access" and "24 Output Power Programming"
  705. default: (0xC6, 0, 0, 0, 0, 0, 0, 0)
  706. """
  707. return tuple(
  708. self._read_burst(
  709. start_register=PatableAddress.PATABLE, length=self._PATABLE_LENGTH_BYTES
  710. )
  711. )
  712. def _set_patable(self, settings: typing.Iterable[int]):
  713. settings = list(settings)
  714. assert all(0 <= l <= 0xFF for l in settings), settings
  715. assert 0 < len(settings) <= self._PATABLE_LENGTH_BYTES, settings
  716. self._write_burst(start_register=PatableAddress.PATABLE, values=settings)
  717. def get_output_power(self) -> typing.Tuple[int, ...]:
  718. """
  719. Returns the enabled output power settings
  720. (up to 8 bytes of the PATABLE register).
  721. see .set_output_power()
  722. """
  723. return self._get_patable()[: self._get_power_amplifier_setting_index() + 1]
  724. def set_output_power(self, power_settings: typing.Iterable[int]) -> None:
  725. """
  726. Configures output power levels by setting PATABLE and FREND0.PA_POWER.
  727. Up to 8 bytes may be provided.
  728. > [PATABLE] provides flexible PA power ramp up and ramp down
  729. > at the start and end of transmission when using 2-FSK, GFSK,
  730. > 4-FSK, and MSK modulation as well as ASK modulation shaping.
  731. For OOK modulation, exactly 2 bytes must be provided:
  732. 0 to turn off the transmission for logical 0,
  733. and a level > 0 to turn on the transmission for logical 1.
  734. >>> transceiver.set_output_power((0, 0xC6))
  735. See "Table 39: Optimum PATABLE Settings for Various Output Power Levels [...]"
  736. and section "24 Output Power Programming".
  737. """
  738. power_settings = list(power_settings)
  739. # checks in sub-methods
  740. self._set_power_amplifier_setting_index(len(power_settings) - 1)
  741. self._set_patable(power_settings)
  742. def _flush_tx_fifo_buffer(self) -> None:
  743. # > Only issue SFTX in IDLE or TXFIFO_UNDERFLOW states.
  744. _LOGGER.debug("flushing tx fifo buffer")
  745. self._command_strobe(StrobeAddress.SFTX)
  746. def transmit(self, payload: bytes) -> None:
  747. """
  748. The most significant bit is transmitted first.
  749. In variable packet length mode,
  750. a byte indicating the packet's length will be prepended.
  751. > In variable packet length mode,
  752. > the packet length is configured by the first byte [...].
  753. > The packet length is defined as the payload data,
  754. > excluding the length byte and the optional CRC.
  755. from "15.2 Packet Format"
  756. Call .set_packet_length_mode(cc1101.PacketLengthMode.FIXED)
  757. to switch to fixed packet length mode.
  758. """
  759. # see "15.2 Packet Format"
  760. # > In variable packet length mode, [...]
  761. # > The first byte written to the TXFIFO must be different from 0.
  762. packet_length_mode = self.get_packet_length_mode()
  763. packet_length = self.get_packet_length_bytes()
  764. if packet_length_mode == PacketLengthMode.VARIABLE:
  765. if not payload:
  766. raise ValueError(f"empty payload {payload!r}")
  767. if len(payload) > packet_length:
  768. raise ValueError(
  769. f"payload exceeds maximum payload length of {packet_length} bytes"
  770. "\nsee .get_packet_length_bytes()"
  771. f"\npayload: {payload!r}"
  772. )
  773. payload = int.to_bytes(len(payload), length=1, byteorder="big") + payload
  774. elif (
  775. packet_length_mode == PacketLengthMode.FIXED
  776. and len(payload) != packet_length
  777. ):
  778. raise ValueError(
  779. f"expected payload length of {packet_length} bytes, got {len(payload)}"
  780. + "\nsee .set_packet_length_mode() and .get_packet_length_bytes()"
  781. + f"\npayload: {payload!r}"
  782. )
  783. marcstate = self.get_main_radio_control_state_machine_state()
  784. if marcstate != MainRadioControlStateMachineState.IDLE:
  785. raise Exception(
  786. f"device must be idle before transmission (current marcstate: {marcstate.name})"
  787. )
  788. self._flush_tx_fifo_buffer()
  789. self._write_burst(FIFORegisterAddress.TX, list(payload))
  790. _LOGGER.info("transmitting 0x%s (%r)", payload.hex(), payload)
  791. self._command_strobe(StrobeAddress.STX)
  792. @contextlib.contextmanager
  793. def asynchronous_transmission(self) -> typing.Iterator[Pin]:
  794. """
  795. > [...] the GDO0 pin is used for data input [...]
  796. > The CC1101 modulator samples the level of the asynchronous input
  797. > 8 times faster than the programmed data rate.
  798. see "27.1 Asynchronous Serial Operation"
  799. >>> with cc1101.CC1101() as transceiver:
  800. >>> transceiver.set_base_frequency_hertz(433.92e6)
  801. >>> transceiver.set_symbol_rate_baud(600)
  802. >>> print(transceiver)
  803. >>> with transceiver.asynchronous_transmission():
  804. >>> # send digital signal to GDO0 pin
  805. """
  806. self._set_transceive_mode(_TransceiveMode.ASYNCHRONOUS_SERIAL)
  807. self._command_strobe(StrobeAddress.STX)
  808. try:
  809. # > In TX, the GDO0 pin is used for data input (TX data).
  810. yield Pin.GDO0
  811. finally:
  812. self._command_strobe(StrobeAddress.SIDLE)
  813. self._set_transceive_mode(_TransceiveMode.FIFO)
  814. def _enable_receive_mode(self) -> None:
  815. self._command_strobe(StrobeAddress.SRX)
  816. def _get_received_packet(self) -> typing.Optional[_ReceivedPacket]: # unstable
  817. """
  818. see section "20 Data FIFO"
  819. """
  820. rxbytes = self._read_status_register(StatusRegisterAddress.RXBYTES)
  821. # PKTCTRL1.APPEND_STATUS is enabled by default
  822. if rxbytes < 2:
  823. return None
  824. buffer = self._read_burst(start_register=FIFORegisterAddress.RX, length=rxbytes)
  825. return _ReceivedPacket(
  826. payload=bytes(buffer[:-2]),
  827. rssi_index=buffer[-2],
  828. checksum_valid=bool(buffer[-1] >> 7),
  829. link_quality_indicator=buffer[-1] & 0b0111111,
  830. )
  831. def _wait_for_packet( # unstable
  832. self,
  833. timeout: datetime.timedelta,
  834. gdo0_gpio_line_name: bytes = b"GPIO24", # recommended in README.md
  835. ) -> typing.Optional[_ReceivedPacket]:
  836. """
  837. depends on IOCFG0 == 0b00000001 (see _configure_defaults)
  838. """
  839. # pylint: disable=protected-access
  840. gdo0 = cc1101._gpio.GPIOLine.find(name=gdo0_gpio_line_name)
  841. self._enable_receive_mode()
  842. if not gdo0.wait_for_rising_edge(consumer=b"CC1101:GDO0", timeout=timeout):
  843. self._command_strobe(StrobeAddress.SIDLE)
  844. _LOGGER.debug(
  845. "reached timeout of %.02f seconds while waiting for packet",
  846. timeout.total_seconds(),
  847. )
  848. return None # timeout
  849. return self._get_received_packet()