[sx126x] Add sx126x component #4794
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughThis pull request updates several version numbers and documentation details. The version identifiers have been revised across configuration files (Doxygen, _static/version, conf.py, and Makefile), shifting from a stable release to a development version. Additionally, new optional configuration variables and documentation entries have been added for various components (CAN bus, ESPHome, logger, PSRAM, SX126x transceivers, and output components), and new CLI options have been introduced. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
components/esphome.rst (1)
69-69: Introduce and Documentdebug_schedulerOptionThe new
debug_schedulerconfiguration variable is clearly added as an optional boolean, which will help users enable scheduler debug logging at the DEBUG level. For improved clarity and usefulness, consider adding a small example snippet or further explanation on when and how this option can be used. This additional context can help users better understand its practical application.components/canbus/esp32_can.rst (1)
31-32: Add new 'tx_enqueue_timeout' configuration optionThe new documentation for the
tx_enqueue_timeoutvariable is clear and concise. It explains that this optional parameter specifies the maximum wait time when the TX queue is full (defaulting to the time it takes to send 10 CAN messages at the given bit rate). Consider including an example or a brief note on how the computed default value is determined for extra clarity.components/psram.rst (1)
26-33: Comprehensive Restrictions SectionThe added "Restrictions" section provides essential cautions regarding PSRAM availability, supported modes, and speed limitations. This extra guidance is very helpful for users. Optionally, you might include a reference or link to the hardware datasheet or module specifications for additional context.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
components/images/sx126x-full.jpgis excluded by!**/*.jpgimages/mcp4461.jpgis excluded by!**/*.jpgimages/sx126x.jpgis excluded by!**/*.jpg
📒 Files selected for processing (12)
Doxygen(1 hunks)Makefile(1 hunks)_static/version(1 hunks)components/canbus/esp32_can.rst(1 hunks)components/esphome.rst(1 hunks)components/index.rst(2 hunks)components/logger.rst(1 hunks)components/output/mcp4461.rst(1 hunks)components/psram.rst(1 hunks)components/sx126x.rst(1 hunks)conf.py(1 hunks)guides/cli.rst(4 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
_static/versioncomponents/esphome.rstcomponents/canbus/esp32_can.rstcomponents/index.rstDoxygenconf.pyMakefilecomponents/psram.rstcomponents/sx126x.rstcomponents/logger.rstcomponents/output/mcp4461.rstguides/cli.rst
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: build
🔇 Additional comments (32)
_static/version (1)
1-1: Version Number Update is ConsistentThe version string has been updated to
2025.4.0-devwhich aligns with the new development cycle. This is clear and correct.Doxygen (1)
41-41: Updated PROJECT_NUMBER to "2025.4.0-dev"This change correctly updates the project version to the new development release. Please verify that all version-related references in the documentation remain consistent with this update.
Makefile (1)
2-2: Updated ESPHOME_REF to 'dev'Switching the
ESPHOME_REFvariable from a fixed version todevaligns with the overall development phase indicated in other files. Make sure that this branch reference ("dev") consistently points to the intended development branch and that the cloning/build process continues to resolve dependencies as expected.conf.py (1)
75-77: Version bumped appropriately for development cycle.The version has been updated from "2025.3" to "2025.4" and the release from "2025.3.3" to "2025.4.0-dev", indicating a shift to a new development cycle. This change aligns with the version updates across other configuration files mentioned in the AI summary.
guides/cli.rst (4)
79-84: Well-structured documentation for new upload_speed option.The new
--upload_speed BAUD_RATEoption is clearly documented with information about default values and environment variable configuration.
109-113: Clear documentation for new reset option.The description of the
--resetoption clearly explains its purpose and configuration method via environment variable.
145-150: Consistent documentation for upload command's upload_speed option.The documentation for this option matches the explanation provided for the same option in the run command, maintaining consistency across the CLI documentation.
271-275: Accurately documented reset option for logs command.The documentation for the
--resetoption in the logs command matches the implementation in the run command, providing consistency across related functionality.components/output/mcp4461.rst (9)
1-10: Comprehensive component introduction.The introduction provides good context about the MCP4461 component, including a link to the official datasheet for further information.
14-17: Correctly structured basic configuration example.The example configuration follows the standard format used in other component documentation.
21-27: Complete configuration variables section.The configuration variables are well-documented with types, descriptions, and default values where applicable.
32-73: Comprehensive output configuration example.The example covers all possible channels and demonstrates the proper way to configure individual outputs, providing a solid reference for users.
79-89: Well-documented output configuration variables.All required and optional parameters are clearly explained with their purposes and default values.
93-95: Helpful implementation details provided.The explanation of internal state handling helps users understand how the component maps float values to tap counts.
96-101: Useful note on state management.The note about using
read_state()andupdate_state()adds valuable context for managing the potentiometer's state at boot.
104-116: Clear practical example for advanced usage.The code example demonstrates how to read and update the potentiometer state during boot sequence, providing a template for users to implement similar functionality.
118-124: Complete references section.The "See Also" section properly links to related documentation and API references.
components/logger.rst (1)
50-57: Improved explanation of deassert_rts_dtr option.The updated description provides much clearer information about how this option affects serial logging connections. The explanation now details the sequential driving of DTR and RTS signals and explains the practical effect of resetting the chip in application mode to capture all boot logs.
components/psram.rst (1)
23-25: Clarify Default Values for Configuration VariablesThe updated descriptions now clearly indicate that the default operating mode is
quadand the default speed is40MHz. This improvement enhances clarity for users configuring PSRAM. Please verify that the formatting and phrasing align with the overall documentation style.components/index.rst (2)
912-912: Verify MCP4661 Naming ConsistencyThe new entry for MCP4661 is added with the path
components/output/mcp4461and imagemcp4461.jpg. Please verify that the component name (MCP4661) matches its directory and image naming (which apparently uses "mcp4461")—this might be an unintentional typographical inconsistency.
1054-1055: New SX1261/2/8 Entry IntegrationThe new entry for the SX1261/2/8 component is appropriately placed in the "Wireless Communication" section. Please confirm that the image
sx126x.jpgexists in the specified location.components/sx126x.rst (11)
1-11: Component Introduction and OverviewThe introduction provides a clear overview of the SX1261/2/8 component, detailing supported transceivers, connection via the SPI bus, the frequency range, and the available modulation types. The inclusion of a datasheet link is an excellent resource for further reference.
17-43: YAML Configuration ExampleThe YAML configuration examples for both the SPI bus setup (lines 17–24) and the SX126x-specific parameters (lines 25–43) illustrate how to configure the component effectively. The examples are well formatted, and the use of underscores (e.g.,
125_0kHz) is clear. Ensure that the indentation and key names remain consistent with other component examples in the documentation.
44-63: Detailed Listing of Configuration VariablesThe documentation now thoroughly lists each configuration variable along with its type, whether it’s required or optional, and a short description of its purpose (e.g., for pins, operational parameters, etc.). This level of detail is very useful for end users to correctly configure the component.
64-78: LoRa Configuration Variables and DefaultsThe LoRa-specific settings are clearly documented with available options for bandwidth, preamble size, spreading factor, coding rate, and sync values. However, note that the documentation indicates the default coding rate is
CR_4_5, while the provided example usesCR_4_6. Please verify whether this discrepancy is intentional or if one of these should be updated for consistency.
80-98: FSK Configuration VariablesThe FSK settings are equally comprehensive. All necessary parameters (such as bandwidth options, bitrate, preamble size, and shaping) are included along with clear descriptions. The guidance on preamble detector behavior is a nice touch. This section is well structured and informative.
99-103: Runtime Configuration NoteThe note reminding users that configuration variables can be modified at runtime via lambdas—and that changes only take effect after calling
configure—is both important and clearly presented.
104-121: Automation Example for Packet HandlingThe
on_packetautomation example effectively demonstrates how to log details from received packets, including the RSSI and, in LoRa mode, the SNR. This practical example will help users implement custom actions upon receiving a packet. Consider explicitly noting thatsnris available only in LoRa mode if that detail isn’t clearly covered elsewhere.
122-179: Actions and Command ExamplesThe documentation presents several well-organized action examples (such as
sx126x.run_image_cal,sx126x.set_mode_tx,sx126x.set_mode_rx, etc.) with corresponding YAML code blocks. These examples serve as a useful guide for programmatically controlling the chip. The structure and formatting are consistent and clear.
185-217: LoRa Configuration Example ConsistencyThis second LoRa configuration example reinforces the earlier settings and includes an explicit header setup along with lambda actions. Note again that the coding rate used here (
CR_4_6) should be verified against the documented default to maintain consistency.
227-267: FSK Mode Configuration ExampleThe FSK-specific configuration example is clear and complete, showing how to set a bit rate of 4800 bps along with all other necessary parameters. The inclusion of both an
on_packetautomation and a button-triggeredsend_packetaction provides a comprehensive usage scenario.
268-276: Additional References in 'See Also'The "See Also" section includes useful links to the index and related components such as the remote transmitter/receiver and API reference. This is an effective way to aid navigation and discovery of related topics.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
components/sx126x.rst (2)
17-43: YAML Configuration Example ClarityThe YAML example clearly demonstrates how to configure both the SPI bus and the
sx126xcomponent. All required keys (likeclk_pin,cs_pin, etc.) and several optional parameters are illustrated.
- It may be beneficial to include inline comments within the YAML snippet to briefly describe the purpose of key parameters (for example, what
pa_powerorbandwidthcontrol).Overall, the example is instructive and aligns well with user expectations.
268-276: See Also Section CompletenessThe "See Also" section effectively provides cross-references to related documentation pages such as the index, remote transmitter/receiver components, and the API reference. This enhances navigability for the user.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
components/sx126x.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
components/sx126x.rst
🔇 Additional comments (19)
components/sx126x.rst (19)
1-3: Title and Component Header ClarityThe title "SX1261/2/8 Component" is concise and clearly communicates the scope of the documentation. It immediately informs the reader about the supported transceiver models.
4-7: SEO Metadata EffectivenessThe SEO block with its description and image reference is well implemented. This metadata will help improve search engine discoverability and the overall presentation of the documentation.
8-11: Comprehensive Component DescriptionThe description provides essential details about the component:
- It mentions the supported transceivers and frequency range.
- It gives a direct link to the datasheet.
- It explains that the transceivers are connected via the SPI Bus.
Ensure that the datasheet URL remains updated in the future.
44-63: General Configuration Variables DocumentationThe list of configuration variables is detailed and user friendly:
- It clearly differentiates between required and optional parameters.
- Descriptions provide useful guidance on what each parameter represents.
This approach should greatly assist users when setting up their component.
64-79: LoRa-Specific Configuration VariablesThe LoRa configuration section is well organized:
- It includes typical parameters such as
bandwidth,payload_length, andcrc_enable.- Enum values and defaults (e.g., for
coding_rateandspreading_factor) are clearly outlined.The documentation is comprehensive and should help users correctly configure LoRa mode.
80-98: FSK-Specific Configuration VariablesThe FSK configuration segment is as detailed as its LoRa counterpart:
- It covers parameters unique to FSK such as
bitrate,preamble_detect,deviation, andshaping.- The provided ranges and enumerated values offer clarity.
Double-check that the hardware specifications for these ranges (like deviation up to 100,000 Hz) are accurate.
99-103: Runtime Configuration NoteThe note highlighting that configuration variables can be modified at runtime using lambdas is very useful. It clearly states that changes will only take effect after calling
configure.
104-110: Automation Capabilities IntroductionThe introduction to automation is concise and clearly describes the purpose of the
on_packettrigger. This section bridges the configuration and real-world application effectively.
111-120: on_packet Lambda ExampleThe lambda example provided for the
on_packetautomation is straightforward:
- It demonstrates logging of packet details with
ESP_LOGD.- It clearly shows how to access variables like
x,rssi, andsnr.Verify that
format_hexis correctly defined or referenced elsewhere in the ESPHome framework.
122-129: Action: sx126x.run_image_cal DocumentationThe documentation for the
sx126x.run_image_calaction is succinct and clear. The accompanying YAML code block (implied) will help users quickly understand how to invoke this calibration action.
131-142: Action: sx126x.set_mode_tx ClarityThe explanation and example for the
sx126x.set_mode_txaction are clear. The YAML snippet effectively demonstrates how to set the transceiver mode to TX.
143-151: Action: sx126x.set_mode_rx ClarityThe documentation for
sx126x.set_mode_rxfollows a similar clear structure as the TX action. The YAML example provided makes it user friendly.
152-160: Action: sx126x.set_mode_sleep ClarityThe instructions for setting the component to sleep mode via
sx126x.set_mode_sleepare straightforward and well presented in the YAML example.
161-169: Action: sx126x.set_mode_standby ClarityThe standby mode action is documented correctly. The example in the YAML code block is consistent with the other action examples, ensuring a uniform configuration approach.
170-179: Action: sx126x.send_packet DocumentationThe
sx126x.send_packetaction is clearly explained:
- The YAML example illustrates how to send a packet using a data array.
- It reinforces the importance of matching the packet length to the
payload_lengthconfiguration.This clear demonstration should facilitate correct usage by end users.
180-184: Packet Data Configuration VariableThe additional configuration variable
datais explained well, emphasizing that the packet length should match the configuredpayload_length. This helps prevent misconfiguration errors.
185-217: Comprehensive LoRa Mode ExampleThe extended YAML configuration example for LoRa mode is highly informative:
- It shows a complete configuration including both basic parameters and automation (
on_packet).- It reinforces the earlier sections by demonstrating real-world usage.
Ensure consistency between these examples and the general documentation provided above.
218-225: Button Action Example in LoRa ModeIncluding an example for a button to trigger packet transmission is an excellent touch. This demonstrates how to integrate the component into interactive ESPHome projects.
227-267: Comprehensive FSK Mode ExampleThe YAML example for FSK mode mirrors the thoroughness of the LoRa example:
- It covers specific FSK parameters and includes an automation via a template button.
- The example confirms that key parameters (like
bitrate,preamble_size, andpreamble_detect) are correctly utilized.It would be beneficial to routinely verify that the enumerated values for parameters such as
bandwidthandshapingcontinue to align with the SX126x hardware capabilities.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
components/sx126x.rst (1)
268-274: "See Also" Section
The "See Also" section effectively provides related documentation and reference links. For improved user navigation, consider adding brief descriptions to these references if space permits.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
components/sx126x.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
components/sx126x.rst
🔇 Additional comments (22)
components/sx126x.rst (22)
1-3: Document Title and Header
The component title and header are clearly defined and accurately reflect the component's purpose.
4-7: SEO Directive Block
The SEO section is correctly included with a concise description and an image directive. Ensure that the image file referenced in the:image:option is accessible.
13-16: Figure Directive: Add Alternate Text for Accessibility
While the figure directive is well formatted, adding an:alt:option (for example,:alt: "SX126x transceiver diagram") would significantly enhance accessibility for users relying on screen readers.-.. figure:: images/sx126x-full.jpg - :align: center - :width: 40.0% +.. figure:: images/sx126x-full.jpg + :align: center + :width: 40.0% + :alt: "SX126x transceiver diagram"
17-24: YAML SPI Configuration Example
The provided YAML example for configuring the SPI bus is clear and concise. It serves as a good starting point for users setting up the component.
25-43: SX126x Component Configuration Example
The component configuration block is comprehensive and well-organized. It clearly outlines both required and optional parameters, which is very helpful for end users.
44-63: Configuration Variables Documentation
The detailed listing of configuration variables, including data types and references to the Pin Schema, is thorough and informative. This level of detail aids users in understanding all available configuration options.
64-79: LoRa Configuration Variables
The section covering LoRa configuration variables is clear, with appropriate explanations for each parameter and sensible defaults.
80-98: FSK Configuration Variables
The FSK configuration parameters are well documented. The descriptions are concise and effectively differentiate the options available for FSK mode.
99-103: Runtime Configuration Note
The note emphasizing that configuration variables can be changed at runtime using lambdas is very useful. It properly guides users regarding when changes take effect.
104-110: Automations Overview – Packet Handling
The automations section introduces theon_packetautomation in a clear and descriptive manner. The information about the lambda parameters (such asx,rssi, andsnr) is particularly valuable.
111-121: Lambda Automation Example
The YAML example for theon_packetautomation is well-formatted, and the debugging log statements provide clear examples of its usage.
122-128: Action: SX126x.run_image_cal
The documentation for the image calibration action is succinct and clear, effectively explaining the purpose of the action.
129-142: Action: SX126x.set_mode_tx
The example provided for setting the component to TX mode is consistent with the style of the documentation and easy to follow.
143-150: Action: SX126x.set_mode_rx
The action to set the component to RX mode is documented in a clear manner, reinforcing the consistent style used throughout the file.
152-160: Action: SX126x.set_mode_sleep
The configuration example for setting sleep mode is clear. The instructions are concise and correctly formatted.
161-168: Action: SX126x.set_mode_standby
The standby action is properly documented. The presented YAML example follows the established format and aids in user comprehension.
170-179: Action: SX126x.send_packet
The documentation for sending a packet is clear and includes a well-structured YAML example for implementation.
180-184: Data Parameter for Packet Action
The description of thedataparameter is clear and directly relates to the payload size stipulation mentioned previously.
185-190: Introduction to LoRa Example Section
The introductory text for the LoRa section is brief yet informative, setting up the expectation for a detailed example afterward.
191-217: Comprehensive LoRa Configuration Example
The LoRa example is extensive and includes all necessary configuration options, including automation elements, which makes it a very practical guide for users.
218-225: Button Automation for Packet Transmission
The button configuration example provides a practical use case for triggering thesx126x.send_packetaction, adding valuable clarity to the documentation.
227-267: FSK Mode Configuration Example
The FSK mode example is detailed and mirrors the structure of the LoRa example, ensuring consistency in the documentation. All relevant FSK parameters are addressed.
|
@bdraco The component was merged but not the docs. Thanks! |
|
I was too tired to double check it again last night. I have it on my list for later today |
|
Ok thanks, sounds good |
|
Thanks @swoboda1337 |
2 participants
Description:
The SX126X component allows you to configure/control the SX1261, SX1261 and SX1268 transceivers in ESPHome. Supported frequencies range from 150 MHz to 960 MHz. Supported modulations include LoRa, FSK, GFSK, MSK and GMSK. There are many devices in the market with an ESP32 already packaged with these radios.
Datasheet: https://www.semtech.com/products/wireless-rf/lora-connect/sx1262#documentation
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.