Hello,
This series adds documentation for the SX130x and SX125x chips.
We are using the yaml binding format and this series builds with
'make dt_binding_check'.
Thanks,
Ben Whitten
Ben Whitten (4):
dt-bindings: lora: sx130x: add basic documentation
dt-bindings: lora: sx125x: add basic documentation
dt-bindings: lora: sx125x: add clock bindings
dt-bindings: lora: sx130x: add clock bindings
.../bindings/net/lora/semtech,sx125x.yaml | 72 ++++++++++
.../bindings/net/lora/semtech,sx130x.yaml | 133 ++++++++++++++++++
2 files changed, 205 insertions(+)
create mode 100644 Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
create mode 100644 Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
--
2.17.1
From: Ben Whitten <[email protected]>
The SX130x family consumes two clocks, a 32 MHz clock provided by a
connected IQ transceiver, and a 133 MHz high speed clock.
In the example we connect the concentrator to a fixed clock providing
the 133 MHz high speed clock, and we connect to a connected transceiver
32 MHz clock.
The connected radios are both fed from a fixed 32 MHz clock, with only
one being the clock source back to the SX130x concentrator.
Signed-off-by: Ben Whitten <[email protected]>
---
v1 -> v2:
* Fixed incorrect usage of clock cells
* Fixed wording in commit and descriptions
---
.../bindings/net/lora/semtech,sx130x.yaml | 39 ++++++++++++++++++-
1 file changed, 38 insertions(+), 1 deletion(-)
diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
index 41919fb67ec4..6f9db3c84385 100644
--- a/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
+++ b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
@@ -15,7 +15,8 @@ description: |
demodulating LoRa signals on 8 channels simultaneously.
It is typically paired with two SX125x IQ radios controlled over an
- SPI directly from the concentrator.
+ SPI directly from the concentrator. One of the radios will provide
+ a 32 MHz clock back into the concentrator.
The concentrator itself is controlled over SPI.
@@ -35,6 +36,20 @@ properties:
maxItems: 1
description: A connection of the reset gpio line.
+ clocks:
+ maxItems: 2
+ items:
+ - description: 32 MHz clock provider (CLK32M)
+ - description: 133 MHz high speed clock provider (CLKHS)
+ description: The chip requires two clock inputs; A 32MHz clock at CMOS
+ level which is provided from a connected radio.
+ And a 133MHz high speed clock at CMOS level provided by an oscillator.
+
+ clock-names:
+ maxItems: 2
+ description: Input clock (CLK32M) name from provider, Input clock (CLKHS)
+ name from provider.
+
radio-spi:
type: object
description: The concentrator can have two radios connected which are
@@ -68,6 +83,20 @@ examples:
#include <dt-bindings/gpio/gpio.h>
+ tcxo: dummy32m {
+ compatible = "fixed-clock";
+ clock-frequency = <32000000>;
+ clock-output-names = "tcxo";
+ #clock-cells = <0>;
+ };
+
+ clkhs: dummy133m {
+ compatible = "fixed-clock";
+ clock-frequency = <133000000>;
+ clock-output-names = "clkhs";
+ #clock-cells = <0>;
+ };
+
spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -77,6 +106,8 @@ examples:
reg = <0>;
reset-gpios = <&pioB 27 GPIO_ACTIVE_HIGH>;
spi-max-frequency = <8000000>;
+ clocks = <&radio1>, <&clkhs>;
+ clock-names = "clk32m", "clkhs";
radio-spi {
#address-cells = <1>;
@@ -85,11 +116,17 @@ examples:
radio0: lora@0 {
compatible = "semtech,sx1257";
reg = <0>;
+ clocks = <&tcxo>;
+ clock-names = "tcxo";
};
radio1: lora@1 {
compatible = "semtech,sx1257";
reg = <1>;
+ clocks = <&tcxo>;
+ clock-names = "tcxo";
+ clock-output-names = "clk32m";
+ #clock-cells = <0>;
};
};
};
--
2.17.1
From: Ben Whitten <[email protected]>
The SX125x consumes a clock (FXOSC) ranging from 32 to 36 MHz.
If the radio is coupled with an SX130x the radio is therefor operating in
master mode and it may also provide a gated version of this clock for the
concentrator. In this case the concentrator is expecting a 32 MHz input
clock.
In the example we connect to the "txco" clock source, represented by a
fixed clock. The radio also provides a clock output named "clk32m" for
consumption by the SX130x concentrator.
Signed-off-by: Ben Whitten <[email protected]>
---
v1 -> v2:
* Fixed incorrect usage of clock cells
* Fixed wording in commit and descriptions
* Dropped enforced clock names
---
.../bindings/net/lora/semtech,sx125x.yaml | 28 +++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
index 4a51a251d97f..8287472fd545 100644
--- a/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
+++ b/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
@@ -27,12 +27,36 @@ properties:
description: The chip select on the SPI bus or radio number in concentrator
, with radio A = 0 and radio B = 1.
+ clocks:
+ maxItems: 1
+ description: Input clock (FXOSC) provider with output ranging from 32 MHz
+ to 36 MHz.
+
+ clock-names:
+ maxItems: 1
+ description: Input clock (FXOSC) name from provider.
+
+ clock-output-names:
+ maxItems: 1
+ description: Output clock (CLK_OUT) name, clock is gated version of the
+ input (FXOSC). Used in master mode operation.
+
+ '#clock-cells':
+ const: 0
+
required:
- compatible
- reg
examples:
- |
+ tcxo: dummy32m {
+ compatible = "fixed-clock";
+ clock-frequency = <32000000>;
+ clock-output-names = "tcxo";
+ #clock-cells = <0>;
+ };
+
spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -40,5 +64,9 @@ examples:
radio0: lora@0 {
compatible = "semtech,sx1257";
reg = <0>;
+ clocks = <&tcxo>;
+ clock-names = "tcxo";
+ clock-output-names = "clk32m";
+ #clock-cells = <0>;
};
};
--
2.17.1
From: Ben Whitten <[email protected]>
Add basic documentation in YAML format for the SX130x series concentrators
from Semtech.
Required is; the location on the SPI bus and the compatible string.
Signed-off-by: Ben Whitten <[email protected]>
---
v1 -> v2:
* Dropped reset-gpios, radio-spi from required.
* Dropped spi-max-frequency from binding.
* Changed compatible to allow fallback from SX1308 to SX1301.
* Wording changes in commit and descriptions.
* Dual licence
* Incorperate Robs comments on child node and spi wrapper
---
.../bindings/net/lora/semtech,sx130x.yaml | 96 +++++++++++++++++++
1 file changed, 96 insertions(+)
create mode 100644 Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
new file mode 100644
index 000000000000..41919fb67ec4
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/lora/semtech,sx130x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Semtech LoRa concentrator
+
+maintainers:
+ - Andreas Färber <[email protected]>
+ - Ben Whitten <[email protected]>
+
+description: |
+ Semtech LoRa concentrator SX130x digital baseband chip is capable of
+ demodulating LoRa signals on 8 channels simultaneously.
+
+ It is typically paired with two SX125x IQ radios controlled over an
+ SPI directly from the concentrator.
+
+ The concentrator itself is controlled over SPI.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - semtech,sx1308
+ - enum:
+ - semtech,sx1301
+
+ reg:
+ maxItems: 1
+ description: The chip select on the SPI bus.
+
+ reset-gpios:
+ maxItems: 1
+ description: A connection of the reset gpio line.
+
+ radio-spi:
+ type: object
+ description: The concentrator can have two radios connected which are
+ contained within the following node.
+
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ patternProperties:
+ "^[a-zA-Z0-9]@[0-1]$":
+ properties:
+ reg:
+ maxItems: 1
+ required:
+ - reg
+
+ required:
+ - '#address-cells'
+ - '#size-cells'
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ concentrator0: lora@0 {
+ compatible = "semtech,sx1301";
+ reg = <0>;
+ reset-gpios = <&pioB 27 GPIO_ACTIVE_HIGH>;
+ spi-max-frequency = <8000000>;
+
+ radio-spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ radio0: lora@0 {
+ compatible = "semtech,sx1257";
+ reg = <0>;
+ };
+
+ radio1: lora@1 {
+ compatible = "semtech,sx1257";
+ reg = <1>;
+ };
+ };
+ };
+ };
--
2.17.1
From: Ben Whitten <[email protected]>
The SX125x family are IQ radio transceivers from Semtech configured over
SPI, they are typically connected to an SX130x series concentrator however
may be connected to a host directly.
Required properties include the radio number of the host or concentrator
bus.
Signed-off-by: Ben Whitten <[email protected]>
---
v1 -> v2:
* Dropped spi-max-frequency binding
* Wording changes to commit and descriptions
* Added spi wrapper suggested by Rob H
* Dual licence
---
.../bindings/net/lora/semtech,sx125x.yaml | 44 +++++++++++++++++++
1 file changed, 44 insertions(+)
create mode 100644 Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
new file mode 100644
index 000000000000..4a51a251d97f
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/lora/semtech,sx125x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Semtech IQ modulator/de-modulator transeiver
+
+maintainers:
+ - Andreas Färber <[email protected]>
+ - Ben Whitten <[email protected]>
+
+description: |
+ The SX125x family are transceivers capable of supporting multiple constant
+ and non-constant envelope modulation schemes.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - semtech,sx1255
+ - semtech,sx1257
+ - semtech,sx1258
+
+ reg:
+ maxItems: 1
+ description: The chip select on the SPI bus or radio number in concentrator
+ , with radio A = 0 and radio B = 1.
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ radio0: lora@0 {
+ compatible = "semtech,sx1257";
+ reg = <0>;
+ };
+ };
--
2.17.1
On Tue, Jan 22, 2019 at 12:07 PM Ben Whitten <[email protected]> wrote:
>
> From: Ben Whitten <[email protected]>
>
> Add basic documentation in YAML format for the SX130x series concentrators
> from Semtech.
> Required is; the location on the SPI bus and the compatible string.
>
> Signed-off-by: Ben Whitten <[email protected]>
> ---
> v1 -> v2:
> * Dropped reset-gpios, radio-spi from required.
> * Dropped spi-max-frequency from binding.
> * Changed compatible to allow fallback from SX1308 to SX1301.
> * Wording changes in commit and descriptions.
> * Dual licence
> * Incorperate Robs comments on child node and spi wrapper
> ---
> .../bindings/net/lora/semtech,sx130x.yaml | 96 +++++++++++++++++++
> 1 file changed, 96 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
>
> diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
> new file mode 100644
> index 000000000000..41919fb67ec4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
> @@ -0,0 +1,96 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/lora/semtech,sx130x.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Semtech LoRa concentrator
> +
> +maintainers:
> + - Andreas Färber <[email protected]>
> + - Ben Whitten <[email protected]>
> +
> +description: |
> + Semtech LoRa concentrator SX130x digital baseband chip is capable of
> + demodulating LoRa signals on 8 channels simultaneously.
> +
> + It is typically paired with two SX125x IQ radios controlled over an
> + SPI directly from the concentrator.
> +
> + The concentrator itself is controlled over SPI.
> +
> +properties:
> + compatible:
> + items:
> + - enum:
> + - semtech,sx1308
> + - enum:
> + - semtech,sx1301
I think you want:
oneOf:
- items:
- enum:
- semtech,sx1308
- const: semtech,sx1301
- items:
- const: semtech,sx1301
That covers these 2 cases:
"semtech,sx1308", "semtech,sx1301"
"semtech,sx1301"
> +
> + reg:
> + maxItems: 1
> + description: The chip select on the SPI bus.
> +
> + reset-gpios:
> + maxItems: 1
> + description: A connection of the reset gpio line.
> +
> + radio-spi:
> + type: object
> + description: The concentrator can have two radios connected which are
> + contained within the following node.
> +
> + properties:
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + patternProperties:
> + "^[a-zA-Z0-9]@[0-1]$":
Is any node name allowed? We like to have generic names. 'lora' is
fine for me, but I'm don't know if other devices could be attached?
I thought up to 8 concentrators was supported? Or channels and radios
aren't 1-1?
This too should have 'type: object' since it is a node name.
> + properties:
> + reg:
> + maxItems: 1
You can add:
minimum: 0
maximum: 1 (or 7?)
> + required:
> + - reg
> +
> + required:
> + - '#address-cells'
> + - '#size-cells'
> +
> +required:
> + - compatible
> + - reg
> +
> +examples:
> + - |
> +
> + #include <dt-bindings/gpio/gpio.h>
> +
> + spi {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + concentrator0: lora@0 {
> + compatible = "semtech,sx1301";
> + reg = <0>;
> + reset-gpios = <&pioB 27 GPIO_ACTIVE_HIGH>;
> + spi-max-frequency = <8000000>;
> +
> + radio-spi {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + radio0: lora@0 {
> + compatible = "semtech,sx1257";
> + reg = <0>;
> + };
> +
> + radio1: lora@1 {
> + compatible = "semtech,sx1257";
> + reg = <1>;
> + };
> + };
> + };
> + };
> --
> 2.17.1
>
On Tue, Jan 22, 2019 at 12:07 PM Ben Whitten <[email protected]> wrote:
>
> From: Ben Whitten <[email protected]>
>
> The SX125x consumes a clock (FXOSC) ranging from 32 to 36 MHz.
> If the radio is coupled with an SX130x the radio is therefor operating in
> master mode and it may also provide a gated version of this clock for the
> concentrator. In this case the concentrator is expecting a 32 MHz input
> clock.
>
> In the example we connect to the "txco" clock source, represented by a
> fixed clock. The radio also provides a clock output named "clk32m" for
> consumption by the SX130x concentrator.
You can squash the clock patches into the 1st 2 patches if you want.
> Signed-off-by: Ben Whitten <[email protected]>
> ---
> v1 -> v2:
> * Fixed incorrect usage of clock cells
> * Fixed wording in commit and descriptions
> * Dropped enforced clock names
> ---
> .../bindings/net/lora/semtech,sx125x.yaml | 28 +++++++++++++++++++
> 1 file changed, 28 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
> index 4a51a251d97f..8287472fd545 100644
> --- a/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
> +++ b/Documentation/devicetree/bindings/net/lora/semtech,sx125x.yaml
> @@ -27,12 +27,36 @@ properties:
> description: The chip select on the SPI bus or radio number in concentrator
> , with radio A = 0 and radio B = 1.
>
> + clocks:
> + maxItems: 1
> + description: Input clock (FXOSC) provider with output ranging from 32 MHz
> + to 36 MHz.
> +
> + clock-names:
> + maxItems: 1
This needs to say what the names are:
items:
- const: txco
With that, you can drop maxItems as that is implied if we list the items.
Just to be clear, this name should be what the clock input is called,
not what drives the input. Seems like that would be 'fxosc'?
> + description: Input clock (FXOSC) name from provider.
> +
> + clock-output-names:
> + maxItems: 1
This too should list the actual names.
> + description: Output clock (CLK_OUT) name, clock is gated version of the
> + input (FXOSC). Used in master mode operation.
> +
> + '#clock-cells':
> + const: 0
> +
> required:
> - compatible
> - reg
>
> examples:
> - |
> + tcxo: dummy32m {
> + compatible = "fixed-clock";
> + clock-frequency = <32000000>;
> + clock-output-names = "tcxo";
> + #clock-cells = <0>;
> + };
> +
> spi {
> #address-cells = <1>;
> #size-cells = <0>;
> @@ -40,5 +64,9 @@ examples:
> radio0: lora@0 {
> compatible = "semtech,sx1257";
> reg = <0>;
> + clocks = <&tcxo>;
> + clock-names = "tcxo";
> + clock-output-names = "clk32m";
> + #clock-cells = <0>;
> };
> };
> --
> 2.17.1
>
Hi,
On 22/01/2019 20:04, Rob Herring wrote:
> On Tue, Jan 22, 2019 at 12:07 PM Ben Whitten <[email protected]> wrote:
>>
>> From: Ben Whitten <[email protected]>
>>
>> Add basic documentation in YAML format for the SX130x series concentrators
>> from Semtech.
>> Required is; the location on the SPI bus and the compatible string.
>>
>> Signed-off-by: Ben Whitten <[email protected]>
>> ---
>> v1 -> v2:
>> * Dropped reset-gpios, radio-spi from required.
>> * Dropped spi-max-frequency from binding.
>> * Changed compatible to allow fallback from SX1308 to SX1301.
>> * Wording changes in commit and descriptions.
>> * Dual licence
>> * Incorperate Robs comments on child node and spi wrapper
>> ---
>> .../bindings/net/lora/semtech,sx130x.yaml | 96 +++++++++++++++++++
>> 1 file changed, 96 insertions(+)
>> create mode 100644 Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
>> new file mode 100644
>> index 000000000000..41919fb67ec4
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/net/lora/semtech,sx130x.yaml
>> @@ -0,0 +1,96 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/net/lora/semtech,sx130x.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Semtech LoRa concentrator
>> +
>> +maintainers:
>> + - Andreas Färber <[email protected]>
>> + - Ben Whitten <[email protected]>
>> +
>> +description: |
>> + Semtech LoRa concentrator SX130x digital baseband chip is capable of
>> + demodulating LoRa signals on 8 channels simultaneously.
>> +
>> + It is typically paired with two SX125x IQ radios controlled over an
>> + SPI directly from the concentrator.
>> +
>> + The concentrator itself is controlled over SPI.
>> +
>> +properties:
>> + compatible:
>> + items:
>> + - enum:
>> + - semtech,sx1308
>> + - enum:
>> + - semtech,sx1301
>
> I think you want:
>
> oneOf:
> - items:
> - enum:
> - semtech,sx1308
> - const: semtech,sx1301
> - items:
> - const: semtech,sx1301
>
> That covers these 2 cases:
> "semtech,sx1308", "semtech,sx1301"
> "semtech,sx1301"
>
Ah yes, that is what I was after. Thanks!
>> +
>> + reg:
>> + maxItems: 1
>> + description: The chip select on the SPI bus.
>> +
>> + reset-gpios:
>> + maxItems: 1
>> + description: A connection of the reset gpio line.
>> +
>> + radio-spi:
>> + type: object
>> + description: The concentrator can have two radios connected which are
>> + contained within the following node.
>> +
>> + properties:
>> + '#address-cells':
>> + const: 1
>> +
>> + '#size-cells':
>> + const: 0
>> +
>> + patternProperties:
>> + "^[a-zA-Z0-9]@[0-1]$":
>
> Is any node name allowed? We like to have generic names. 'lora' is
> fine for me, but I'm don't know if other devices could be attached?
>
This sub bus will only have IQ radios attached to it, perhaps 'radio@0'
as the system can handle other modulations.
> I thought up to 8 concentrators was supported? Or channels and radios
> aren't 1-1?
You can have multiple concentrator chips (SX130x) however each one may
have up to two IQ radios (SX125x) attached to its bus.
And in terms of channels the system can listen on, the concentrator has
9 LoRa demodulators and 1 (G)FSK demodulator.
>
> This too should have 'type: object' since it is a node name.
>
Ah yes
>> + properties:
>> + reg:
>> + maxItems: 1
>
> You can add:
> minimum: 0
> maximum: 1 (or 7?)
>
>> + required:
>> + - reg
>> +
>> + required:
>> + - '#address-cells'
>> + - '#size-cells'
>> +
>> +required:
>> + - compatible
>> + - reg
>> +
>> +examples:
>> + - |
>> +
>> + #include <dt-bindings/gpio/gpio.h>
>> +
>> + spi {
>> + #address-cells = <1>;
>> + #size-cells = <0>;
>> +
>> + concentrator0: lora@0 {
>> + compatible = "semtech,sx1301";
>> + reg = <0>;
>> + reset-gpios = <&pioB 27 GPIO_ACTIVE_HIGH>;
>> + spi-max-frequency = <8000000>;
>> +
>> + radio-spi {
>> + #address-cells = <1>;
>> + #size-cells = <0>;
>> +
>> + radio0: lora@0 {
>> + compatible = "semtech,sx1257";
>> + reg = <0>;
>> + };
>> +
>> + radio1: lora@1 {
>> + compatible = "semtech,sx1257";
>> + reg = <1>;
>> + };
>> + };
>> + };
>> + };
>> --
>> 2.17.1
>>
Thanks!
Ben Whitten