Added frequency modules, Improved documentation, Bumping to v0.6.0

Update e32-443t37s-wiring.png, extra_styles.css, and 22 more files...
aziascreations · Jun 13, 2023 · 266577d · 266577d
1 parent 1ad58e2
commit 266577d
Show file tree

Hide file tree

Showing 24 changed files with 247 additions and 124 deletions.
diff --git a/docs/_static/e32-443t37s-wiring.png b/docs/_static/e32-443t37s-wiring.png
diff --git a/docs/_static/extra_styles.css b/docs/_static/extra_styles.css
@@ -0,0 +1,3 @@
+img {
+    border-radius: 1rem;
+}
diff --git a/docs/_static/wiring_blackpill_temp.jpg b/docs/_static/wiring_blackpill_temp.jpg
diff --git a/docs/_static/wiring_esp32s3_temp.jpg b/docs/_static/wiring_esp32s3_temp.jpg
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,9 +1,27 @@
+.. role:: raw-html(raw)
+    :format: html
+
 .. automodule:: ebyte_e32
     :members:
 
-.. automodule:: ebyte_e32.eu433
+:raw-html:`<hr>`
+
+.. automodule:: ebyte_e32.exceptions
+    :members:
+
+:raw-html:`<hr>`
+
+.. automodule:: ebyte_e32.f433
+    :members:
+
+.. automodule:: ebyte_e32.f868
+    :members:
+
+.. automodule:: ebyte_e32.f915
     :members:
 
+:raw-html:`<hr>`
+
 .. automodule:: ebyte_e32.t20
     :members:
 
@@ -12,3 +30,6 @@
 
 .. automodule:: ebyte_e32.t33
     :members:
+
+.. automodule:: ebyte_e32.t37
+    :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,16 +31,15 @@
 exclude_patterns = []
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 html_favicon = "_static/favicon.ico"
-
+html_css_files = ["extra_styles.css"]
 
 # The short X.Y version.
-version = "0.3"
+version = "0.6"
 # The full version, including alpha/beta/rc tags.
-release = "0.3.0"
+release = "0.6.0"
diff --git a/docs/examples_wiring.rst b/docs/examples_wiring.rst
@@ -0,0 +1,55 @@
+.. role:: raw-html(raw)
+    :format: html
+
+Wiring
+------
+The pictures in this section will be changed to better ones soon.
+
+ESP32-S3
+^^^^^^^^
+TODO
+
+.. image:: _static/wiring_esp32s3_temp.jpg
+   :width: 80%
+   :alt: Picture of a E32-433T20D connected to an ESP32-S3.
+   :align: center
+
+:raw-html:`<br>`
+
+STM32 Black Pill
+^^^^^^^^^^^^^^^^
+In this example, E32 module is connected to a STM32F411CE Black Pill.
+
+This MCU requires the some specific pins to be used for the UART bus.
+:raw-html:`<br>`
+The MCU's `USART1` pins are both used out-of-the-box, so we'll need to use the `USART2` pins.
+
++---------+--------------+-----------+---------------+------------------+
+| E32 Pin | Pin constant | STM32 Pin | Pin function  | Alternatives     |
++=========+==============+===========+===============+==================+
+| **M0**  | ``board.B3`` | ``PB3``   | Generic I/O   | Any output pin   |
++---------+--------------+-----------+---------------+------------------+
+| **M1**  | ``board.B4`` | ``PB4``   | Generic I/O   | Any output pin   |
++---------+--------------+-----------+---------------+------------------+
+| **RXD** | ``board.A2`` | ``PA2``   | ``USART2_TX`` | **None**         |
++---------+--------------+-----------+---------------+------------------+
+| **TXD** | ``board.A3`` | ``PA3``   | ``USART2_RX`` | **None**         |
++---------+--------------+-----------+---------------+------------------+
+| **AUX** | ``board.B7`` | ``PB7``   | Generic I/O   | Any input pin    |
++---------+--------------+-----------+---------------+------------------+
+
+.. image:: _static/wiring_blackpill_temp.jpg
+   :width: 80%
+   :alt: Picture of a E32-433T20D connected to a STM32F411CE Black Pill.
+   :align: center
+
+:raw-html:`<br>`
+
+Other boards
+^^^^^^^^^^^^
+Other boards should work similarly to the `ESP32-S3` unless they have specific limitations.
+
+If you have any other that have some special requirements or you think are worth mentioning, don't hesitate to create
+an issue on the repo with a picture of your wiring.
+
+We'd be glad to include it on this page.
diff --git a/docs/index.rst b/docs/index.rst
@@ -21,6 +21,7 @@ Table of Contents
 .. toctree::
     :caption: Examples
 
+    examples_wiring
     examples_instantiation
     examples_config
     examples_uart

diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -68,7 +68,11 @@ Recommended Links
 
 * `LoRaWAN Regional Parameters  (By LoRa Alliance) <https://resources.lora-alliance.org/home/rp002-1-0-4-regional-parameters>`_
 
-* https://www.raveon.com/the-lora-protocol/
+* `LoRa - Packet size considerations  (By SemTech) <https://lora-developers.semtech.com/documentation/tech-papers-and-guides/the-book/packet-size-considerations/>`_
+
+* `LoRaWAN - Regional parameters  (By LoRa Alliance) <https://resources.lora-alliance.org/home/rp002-1-0-4-regional-parameters>`_
+
+* `LoRa data rate calculator (By rfwireless-world.com) <https://www.rfwireless-world.com/calculators/LoRa-Data-Rate-Calculator.html>`_
 
 License
 ^^^^^^^

diff --git a/docs/technical_details_e32.rst b/docs/technical_details_e32.rst
@@ -19,14 +19,14 @@ Wiring
 +------------+---------------------------------+
 | `AUX`      | Any digital input pin**         |
 +------------+---------------------------------+
-| `VCC`      | Power supply***                 |
+| `VCC`      | Power supply                    |
 +------------+---------------------------------+
 
 \*: Some devices may require you to use very specific pins for the UART bus.
 :raw-html:`<br>`
 \*\*: This pin can be left floating, but the module's AUX response times will be estimated and inaccurate.
 :raw-html:`<br>`
-\*\*\*: Should be between 3.3V and 5.0V, more than 5.2V can cause damage, and some modules support 2.3V !
+\*\*\*: Should be between 3.3V and 5.0V **for less than 5W**, more than 5.2V can cause damage, and some modules support 2.3V !
 
 Model Number Structure
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -64,13 +64,13 @@ Max Power
 :raw-html:`<br>`
 ``33`` ➜ 33dBm / 2W
 :raw-html:`<br>`
-``37`` ➜ 37dBm / 5W
+``37`` ➜ 37dBm / 5W  `(Special PSU requirements)`
 
 Form Factor
 """""""""""
-``D`` ➜ DIP (Dual In-line Package)
+``D`` ➜ DIP `(Dual In-line Package)`
 :raw-html:`<br>`
-``S`` ➜ SMD (Surface Mount Device)
+``S`` ➜ SMD `(Surface Mount Device)`
 
 Optional Variant
 """"""""""""""""
@@ -221,4 +221,4 @@ We also keep copies of them over at `files.nibblepoker.lu <https://files.nibblep
 just in case.
 
 Alternatively, `manualslib.com <https://www.manualslib.com/products/Ebyte-E32-Series-10450561.html>`_ has a pretty good
-collection of the most common one, as well as some that cannot be found elsewhere.
+collection of the most common ones.
diff --git a/docs/technical_details_lora.rst b/docs/technical_details_lora.rst
@@ -1,9 +1,7 @@
-LoRa
-----
+LoRa (TODO)
+-----------
 TODO
 
-All the information shown on this page is taken from ???.
-
 Spreading Factor
 ^^^^^^^^^^^^^^^^
 TODO
diff --git a/docs/technical_details_lorawan.rst b/docs/technical_details_lorawan.rst
@@ -1,5 +1,5 @@
-LoRaWAN
--------
+LoRaWAN (TODO)
+--------------
 TODO
 
 Make it short, and link to official spec sheet.

diff --git a/docs/technical_details_wiring.rst b/docs/technical_details_wiring.rst
@@ -1,10 +1,35 @@
+.. role:: raw-html(raw)
+    :format: html
+
 Power-supply Considerations
 ---------------------------
-TODO
 
-Problems noticed:
+Voltage
+^^^^^^^
+Most modules require their VIN pin to be between 3.3V and 5.0V
+
+They shouldn't have more than 5.2V as it can cause damage to your module.
+
+The `E32-443T37S` module is a special case as it requires between 4.5V and 15V.
+
+Extra Passive Components
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Low power modules
+"""""""""""""""""
+You should preferably put a small decoupling capacitor as close to the `VIN` and `GND` pins as possible.
+
+Some people on `mischianti.org <https://mischianti.org/forums/topic/lora-e32-decupling-capacitor/>`_
+have apparently emailed Ebyte and were recommended the following:
+
+    `A capacitor between 100nF/0.1µF and 1000nF/1µF.`
+
+High power modules
+""""""""""""""""""
+The `E32-443T37S` module requires a more complex setup as shown below:
 
-* Crashes when switching TX after sending packages for a while:
+.. image:: _static/e32-443t37s-wiring.png
+   :width: 90%
+   :align: center
 
-  * VIN ripples
-  * Involuntary inductor  (Could be really bad at 5V !!!)
+:raw-html:`<br>`
diff --git a/ebyte_e32/__version__.py b/ebyte_e32/__version__.py
@@ -6,6 +6,6 @@
 """
 
 MAJOR = 0
-MINOR = 5
+MINOR = 6
 PATCH = 0
 VERSION = f"{MAJOR}.{MINOR}.{PATCH}"
diff --git a/ebyte_e32/eu433.py b/ebyte_e32/eu433.py
diff --git a/ebyte_e32/f433.py b/ebyte_e32/f433.py
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 Herwin Bozet
+#
+# SPDX-License-Identifier: MIT
+"""
+`ebyte_e32.f443`
+====================================================
+* Author(s): Herwin Bozet
+"""
+
+CHANNEL_COUNT = 32
+"""Amount of available channels."""
+
+FREQUENCY_MINIMUM = 410.0
+"""Minimum frequency in MHz corresponding to channel `0`."""
+
+FREQUENCY_MAXIMUM = 441.0
+"""Maximum frequency in MHz corresponding to channel `31`."""
+
+FREQUENCY_STEP = 1.0
+"""Frequency difference between channels in MHz."""
diff --git a/ebyte_e32/f868.py b/ebyte_e32/f868.py
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 Herwin Bozet
+#
+# SPDX-License-Identifier: MIT
+"""
+`ebyte_e32.f868`
+====================================================
+* Author(s): Herwin Bozet
+"""
+
+CHANNEL_COUNT = 32
+"""Amount of available channels."""
+
+FREQUENCY_MINIMUM = 862.0
+"""Minimum frequency in MHz corresponding to channel `0`."""
+
+FREQUENCY_MAXIMUM = 893.0
+"""Maximum frequency in MHz corresponding to channel `31`."""
+
+FREQUENCY_STEP = 1.0
+"""Frequency difference between channels in MHz."""
diff --git a/ebyte_e32/f915.py b/ebyte_e32/f915.py
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 Herwin Bozet
+#
+# SPDX-License-Identifier: MIT
+"""
+`ebyte_e32.f915`
+====================================================
+* Author(s): Herwin Bozet
+"""
+
+CHANNEL_COUNT = 32
+"""Amount of available channels."""
+
+FREQUENCY_MINIMUM = 900.0
+"""Minimum frequency in MHz corresponding to channel `0`."""
+
+FREQUENCY_MAXIMUM = 931.0
+"""Maximum frequency in MHz corresponding to channel `31`."""
+
+FREQUENCY_STEP = 1.0
+"""Frequency difference between channels in MHz."""
diff --git a/ebyte_e32/ism170.py b/ebyte_e32/ism170.py
diff --git a/ebyte_e32/t20.py b/ebyte_e32/t20.py
@@ -26,4 +26,4 @@ class TransmitPower:
     "10 mW"
 
     TX_POWER_DEFAULT = TX_POWER_20DBM
-    "Default TX power for T20 modules"
+    "Default TX power for modules with the T20 suffix"
diff --git a/ebyte_e32/t30.py b/ebyte_e32/t30.py
@@ -26,4 +26,4 @@ class TransmitPower:
     "~125 mW"
 
     TX_POWER_DEFAULT = TX_POWER_30DBM
-    "Default TX power for T30 modules"
+    "Default TX power for modules with the T30 suffix"
diff --git a/ebyte_e32/t33.py b/ebyte_e32/t33.py
@@ -26,4 +26,4 @@ class TransmitPower:
     "~250 mW"
 
     TX_POWER_DEFAULT = TX_POWER_33DBM
-    "Default TX power for T33 modules"
+    "Default TX power for modules with the T33 suffix"