Communication Protocols |

🧩 Zephyr SPI Notes for Nordic microcontrollers - Part 3

Tue, 14 Jul 2026 00:00:00 +0000

Once the SPI controller, pinctrl configuration, child nodes, and basic Zephyr API usage are in place, the next challenge is making the complete system reliable on real hardware.

A configuration may compile correctly and still fail because of an incorrect chip-select mapping, an unsuitable clock frequency, a floating MISO line, an unpowered peripheral, a missing binding, or a transaction that doesn’t match the device datasheet.

This final part focuses on that integration and debugging stage.

It covers how to choose a practical SPI frequency, manage several devices on the same bus, handle chip-select and interrupt GPIOs, create bindings for custom drivers, and integrate out-of-tree modules into a Zephyr workspace.

It also presents a layered debugging approach that moves from build configuration and runtime readiness to logic-analyzer captures, signal integrity, power sequencing, and incremental board bring-up.

The goal is not only to make one SPI transaction work. It is to understand where a failure begins, verify each layer independently, and build a communication path that remains reliable as more devices, interrupts, higher frequencies, and power-management features are added.

8. Frequency strategy

Each child device can define its own spi-max-frequency:

afe0 {
 spi-max-frequency = <24000000>;
};

flash@1 {
 spi-max-frequency = <83000000>;
};

acc@2 {
 spi-max-frequency = <4000000>;
};

The spi-max-frequency property belongs to the SPI child node because each device may support a different maximum SPI clock frequency.

However, this value is only one part of the decision.

The practical maximum SPI frequency is limited by:

1. The SPI peripheral’s specifications.
2. The capabilities of the selected nRF52840 SPIM instance.
3. The PCB layout and signal integrity.
4. The selected GPIO drive strength.
5. The voltage domain and loading on the bus.
6. The quality of CS, SCK, MOSI, and MISO waveforms.

A safe approach is to treat spi-max-frequency as an upper limit, not as the initial bring-up frequency. Don’t blindly copy the device’s maximum supported frequency from its datasheet into the devicetree.

For example, this is misleading on a typical nRF52840 SPIM bus:

flash: flash@1 {
 reg = <1>;
 spi-max-frequency = <83000000>; 
};

Even if the flash memory itself supports a very high SPI clock, the nRF52840 SPIM controller and the board layout may impose lower limits.

A more conservative starting configuration would be:

flash: flash@1 {
 reg = <1>;
 spi-max-frequency = <1000000>;  # first bring-up
};

The frequency can then be increased gradually after obtaining reliable READ_ID and status-register responses.

A suggested bring-up sequence is:

Stage	SPI frequency	Goal
First power-on	500 kHz – 1 MHz	Verify wiring, CS behavior, and MISO activity
Identity reads stable	1 – 4 MHz	Confirm that responses are repeatable
Functional tests	Device-dependent	Test register access, FIFO operation, and status reads
Optimization	Up to the device and layout limits	Increase speed only after confirming reliable operation and acceptable signal integrity

9. Chip-select rules

In SPI, SCK, MOSI, and MISO are shared by all devices on the bus, but each device needs its own chip-select line.

SCK -> shared
MOSI -> shared
MISO -> shared
CS0 -> accelerometer
CS1 -> flash memory
CS2 -> AFE

The chip-select line determines which SPI peripheral is active during a transaction.

Only one CS line should be active during a transaction.

Most SPI devices use an active-low chip-select signal:

CS high -> device not selected
CS low -> device selected

Therefore, the devicetree configuration commonly uses:

GPIO_ACTIVE_LOW

For example:

cs-gpios = <&gpio0 17 GPIO_ACTIVE_LOW>;

Physical pull-up recommendation

On custom boards, adding a physical pull-up resistor to each CS line is often a good design practice.

The appropriate resistance depends on the connected device, the board design, and the recommendations in the device datasheet.

CS pull-ups help because:

- During reset, MCU pins may be high impedance.
- Before Zephyr configures GPIOs, CS may float.
- During power sequencing, a floating CS can accidentally select a device.
- A selected SPI device may drive MISO unexpectedly.
- Two selected devices can fight each other on MISO.

On custom boards,, CS pull-ups are more important than pull-ups on SCK, MOSI, or MISO.

A typical recommendation is:

CS lines -> add external pull-ups, especially on custom boards
SCK / MOSI -> usually no pull-up needed; driven by SPI master
MISO -> usually no pull-up needed for normal operation

A weak pull on MISO can sometimes make idle logic-analyzer traces easier to read, but it isn’t normally required for SPI communication and shouldn’t be used to hide a real bus-contention problem.

Do not manually toggle CS unless you really need to

When using:

spi_write_dt()
spi_read_dt()
spi_transceive_dt()

with a valid spi_dt_spec, Zephyr can control the CS GPIO automatically for the transaction.

Therefore, avoid manually toggling CS around typical SPI calls:

gpio_pin_set_dt(&cs_gpio, 0);
spi_transceive_dt(&spi_dev, &tx, &rx);
gpio_pin_set_dt(&cs_gpio, 1);

That can conflict with the CS control already defined throughcs-gpios.

Manual CS control is an advanced case, useful only when a device protocol explicitly requires behavior that the SPI transaction API cannot express.

For most use cases, let Zephyr control CS through cs-gpios.

Common CS mistakes

Mistake 1: Wrong `reg` index

cs-gpios = <&gpio0 17 GPIO_ACTIVE_LOW>,
 <&gpio0 15 GPIO_ACTIVE_LOW>,
 <&gpio0 13 GPIO_ACTIVE_LOW>;

afe: optical-afe@0 {
 reg = <0>;  # Subtle mistake. Actually selects P0.17, not P0.13
};

If the device is wired to P0.13, then it should be:

afe: optical-afe@2 {
 reg = <2>;
};

Mistake 2: GPIO controller disabled

This is incomplete:

&spi3 {
 cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
};

if &gpio1 is not enabled.

&gpio1 {
 status = "okay";
};

Mistake 3: CS pin also used by another peripheral

If the CS pin is already used by UART, I2C, PWM, NFC, buttons, LEDs, or another shield definition, SPI may compile but fail electrically.

Always compare:

- schematic
- PCB net names
- board .dts / .dtsi
- overlay file
- generated build/zephyr/zephyr.dts

10. Multiple SPI buses vs. multiple devices on one bus

There are two common ways to connect several SPI peripherals:

Place multiple devices on the same SPI bus and assign a separate CS line to each one.
Use separate SPI buses for devices with incompatible electrical, timing, or bandwidth requirements.

One bus, multiple CS lines

In this arrangement:

SCK, MOSI, MISO are shared.
Each device has its own CS line.
Only one device should be selected at a time.

This is usually best when:

- Devices share the same I/O voltage.
- Devices are physically close to the MCU.
- The total bandwidth requirement is reasonable.
- The layout is clean and trace lengths are controlled.
- The devices can tolerate the same electrical bus conditions.
- Software can safely switch frequency and mode per device.

This is a good default for boards that have several SPI peripherals, but they don’t all need to communicate continuously at max speed.

Separate SPI buses

A separate SPI bus can be useful when one device has special requirements.

This is preferable when:

- One device needs much higher throughput.
- One device is electrically noisy.
- One device is power-gated while others remain active.
- One device has strict timing or signal-integrity requirements.
- Devices require different modes and switching becomes risky.
- The PCB layout is cleaner with separate buses.
- Pin budget allows the separation.

11. Interrupt pins aren’t SPI pins

Some SPI devices expose extra pins such as:

INT
DRDY
RESET
BUSY
ENABLE
FIFO interrupt

These signals are not part of the SPI bus itself. They are handled as regular GPIOs.

For example, an AFE connected through SPI may also provide an interrupt output:

afe: optical-afe@2 {
 compatible = "manufacturer,reference";
 reg = <2>;
 spi-max-frequency = <10000000>;
 int1-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>;
};

In this configuration:

SPI communication still uses the SPI bus.
The interrupt signal uses GPIO P0.08.

Where interrupt properties belong

Interrupt GPIO properties normally belong in the child device node:

afe: optical-afe@2 {
 int1-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>;
};

They don’t belong in the SPI bus pinctrl group.

Correct:

&pinctrl {
 spi3_default: spi3_default {
 group1 {
 psels = <NRF_PSEL(SPIM_SCK, 0, 19)>,
 <NRF_PSEL(SPIM_MOSI, 0, 21)>,
 <NRF_PSEL(SPIM_MISO, 0, 23)>;
 };
 };
};

Incorrect:

&pinctrl {
 spi3_default: spi3_default {
 group1 {
 psels = <NRF_PSEL(SPIM_SCK, 0, 19)>,
 <NRF_PSEL(SPIM_MOSI, 0, 21)>,
 <NRF_PSEL(SPIM_MISO, 0, 23)>,
 <NRF_PSEL(SPIM_INT, 0, 8)>; 
 };
 };
};

The binding must define the property

If the child uses a generic compatible such as:

compatible = "vnd,spi-device";

then not every custom property is automatically valid.

A property such as:

int1-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>;

should be described in a binding if the node is intended to pass validation cleanly.

A custom binding should include:

properties:
 int1-gpios:
 type: phandle-array
 required: false
 description: Interrupt 1 GPIO

Application-level interrupt setup

In application code or driver code, the interrupt pin is usually handled with a gpio_dt_spec.

Example:

#define AFE_NODE DT_NODELABEL(afe)

static const struct gpio_dt_spec afe_int = GPIO_DT_SPEC_GET_OR(AFE_NODE, int1_gpios, {0});
static struct gpio_callback afe_int_cb;
static struct k_work afe_work;

A typical interrupt callback should stay short:

static void afe_gpio_callback(const struct device *port,
 struct gpio_callback *cb,
 gpio_port_pins_t pins){
 k_work_submit(&afe_work);
}

Then the work handler can perform heavier processing:

static void afe_work_handler(struct k_work *work){
 // Read status/FIFO over SPI here, outside the GPIO ISR context.
}

Why defer work?

Avoid performing long SPI transactions or heavy data processing directly inside a GPIO interrupt service routine.

A better pattern is:

GPIO interrupt triggers.
ISR submits k_work.
Work handler performs SPI read/status handling.

This keeps the interrupt routine short and moves the longer operation into thread context.

It also makes the application easier to maintain because interrupt detection and SPI processing remain separate responsibilities.

12. Bindings for custom drivers

A generic SPI child node can be enough when the application performs transactions directly through SPI_DT_SPEC_GET().

However, when the peripheral has its own reusable driver, custom GPIO properties, initialization procedure, or sensor API implementation, it is better to create a dedicated devicetree binding and driver.

An out-of-tree module could begin with this structure:

sensing_storage/
├── zephyr/ │
 └── module.yml
├── dts/
│ └── bindings/
│ └── sensor/
│ └── manufacturer,reference.yaml
├── drivers/
│ └── sensor/
│ └── reference/
│ ├── CMakeLists.txt
│ ├── Kconfig
│ └── reference.c
├── CMakeLists.txt
└── Kconfig

The binding describes the device properties that may appear in devicetree.

For example:

# dts/bindings/sensor/manufacturer,device.yaml

description: |
 Optical analog front end accessed through application-managed SPI transactions

compatible: "manufacturer,reference"

include: [sensor-device.yaml, spi-device.yaml]

properties:
 reg:
 required: true
 spi-max-frequency:
 type: int
 required: true
 description: Max SPI clock in Hz (up to 80000000)

 int1-gpios:
 type: phandle-array
 required: false
 description: Optional interrupt GPIO connected to the sensor’s INT1 pin

 reset-gpios:
 type: phandle-array
 required: false
 description: Optional reset GPIO

The important line is:

include: [sensor-device.yaml, spi-device.yaml]

That tells Zephyr this child is an SPI device and should accept normal SPI child properties such as:

reg
spi-max-frequency

Devicetree node after adding the binding

The device can then be represented in devicetree as:

afe: optical-afe@2 {
 compatible = "manufacturer,reference";
 reg = <2>;
 spi-max-frequency = <1000000>;
 int1-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>;
};

At this point, the node is no longer just a generic SPI connection. It is intended to represent a real SPI device.

However, a binding alone does not create a Zephyr device object.

Then, to use:

const struct device *dev = DEVICE_DT_GET(DT_NODELABEL(afe));

you also need a driver that creates the device object. That means:

Binding exists
-> Zephyr can validate the devicetree node and generate its metadata.

Driver is compiled
-> Driver initialization code is included in the firmware.

Driver creates the device object
-> DEVICE_DT_GET() can refer to that device.

Without that driver-created device object, the devicetree node may be valid while DEVICE_DT_GET() still produces a linker error.

Connecting the driver to Kconfig and CMake

The driver directory can contain a local Kconfig file:

config DEVICE3
    bool "Enable the reference optical AFE driver"
    depends on SPI
    depends on GPIO
    default n
    help
        Enables support for the reference optical analog front end.

Its CMakeLists.txt can add the driver source when the symbol is enabled:

zephyr_library()

zephyr_library_sources_ifdef(
 CONFIG_DEVICE3
 reference.c
)

The module’s top-level CMakeLists.txt can then include the driver directory:

add_subdirectory(drivers/sensor/reference)

Similarly, the module’s top-level Kconfig can include the driver configuration:

rsource "drivers/sensor/reference/Kconfig"

The exact organization can vary, but the purpose remains the same:

Kconfig decides whether the driver is enabled.
CMake decides which source files are compiled.
The driver source creates the Zephyr device object.

What `zephyr/module.yml` does

The zephyr/module.yml file tells Zephyr how the external repository participates in the build.

A minimal example is:

build:
 cmake: .
 kconfig: Kconfig

This means:

cmake: .
 -> Use the CMakeLists.txt file at the module root.

kconfig: Kconfig
 -> Include the Kconfig file at the module root.

The module can also contain devicetree bindings under dts/bindings. Once Zephyr recognizes the repository as a module, it can discover those bindings as part of the build.

Making the module visible to Zephyr

Creating the module files is not enough by itself. Zephyr must also know where the module repository is located.

There are two common approaches:

Pass the local module path directly when building.
Add the repository to the west workspace manifest.

The first option is convenient during early development. The second is more suitable when the module should become a reproducible part of the project workspace.

Option 1: Pass `ZEPHYR_EXTRA_MODULES` during build

For a local module outside the west workspace, build with:

west build -b smart_custom_board/nrf52840 app \
 -- -DZEPHYR_EXTRA_MODULES=/absolute/path/to/sensing_storage

This command can be read in two parts:

west build -b smart_custom_board/nrf52840 app
    -> Ask west to configure and build the application for the
 selected board.
--
    -> Stop processing west arguments. Everything after this marker
 is passed to CMake.

-DZEPHYR_EXTRA_MODULES=/absolute/path/to/sensing_storage
-> Tell the Zephyr build system to include this additional
 module directory.

In other words, west launches the build, but ZEPHYR_EXTRA_MODULES is a Zephyr CMake setting.

This approach is useful when:

- The module is still under development.
- The module exists only on the local computer.
- You want to test the module without changing west.yml.
- The module path differs between development environments.

If the build directory was previously configured without the module, perform a pristine build:

west build -p always -b smart_custom_board/nrf52840 app -- \
-DZEPHYR_EXTRA_MODULES=/absolute/path/to/sensing_storage

The -p always option forces west to recreate the build directory configuration, preventing old CMake state from hiding module changes.

One limitation is that an absolute local path is not portable. Another developer—or a continuous-integration server—may store the module somewhere else.

Option 2: Add the module to `west.yml`

For a module stored in its own Git repository, it can be added to the workspace manifest:

manifest:
    projects:
        - name: sensing-storage
          url: https://example.com/your-account/sensing-storage.git
 revision: main
          path: modules/sensing_storage

The fields mean:

name
    -> The project name used by west.

url
    -> The Git repository containing the module.

revision
    -> The branch, tag, or commit that west should check out.

path
    -> Where the repository will be placed inside the west workspace.

After updating the manifest, run:

west update

West then retrieves the repository and places it at the configured workspace path.

If that repository contains a valid zephyr/module.yml, Zephyr can recognize it as a module during the build.

A west project and a Zephyr module are related concepts, but they are not identical:

west project
    -> A Git repository managed by the west manifest.

Zephyr module
    -> A repository that provides Zephyr build content,
 commonly described through zephyr/module.yml.

A west project may contain tools, documentation, or other files and may not be a Zephyr module. Conversely, a local Zephyr module can be included through ZEPHYR_EXTRA_MODULES without being managed by west.yml.

Using west.yml is usually preferable when:

- Multiple developers need the same repository.
- The project is built in continuous integration.
- A specific module revision must be reproducible.
- Running west update should retrieve all required dependencies.
- The module is a long-term part of the product workspace.

13. Early debugging checklist

Debug SPI in layers. Don’t jump directly to rewriting the driver.Debug SPI in layers. Do not jump directly to rewriting the driver or changing the transaction code.

A layered approach helps determine whether the failure comes from.

Layer 1: build configuration

Check:

[ ] CONFIG_SPI=y
[ ] CONFIG_GPIO=y
[ ] CONFIG_PINCTRL=y
[ ] The intended SPI node has status = "okay"
[ ] The GPIO controller used for CS has status = "okay"
[ ] The pinctrl labels referenced by the SPI node exist
[ ] The child node compatible matches the intended access pattern

Useful generated files include:

build/zephyr/.config
build/zephyr/zephyr.dts
build/zephyr/include/generated/zephyr/devicetree_generated.h

Common build-time failures

Symptom	Likely cause	Fix
`compatible "nordic,nrf-spim" not recognized`	Wrong devicetree context, missing SoC include, or invalid board inheritance	Check board DTS, SoC DTSI, NCS version, and perform a pristine build
`__device_dts_ord_*` link error	The C code requested a device object that no compiled driver created	Use SPI_DT_SPEC_GET() for an application-managed SPI child, or compile a real driver for that compatible
Child property rejected	Binding doesn’t allow that property	Add an appropriate custom binding or remove the unsupported property
SPI node disabled	`status = "okay"` missing or overridden	Inspect `build/zephyr/zephyr.dts`
Kconfig warning: symbol assigned but not used	Wrong symbol, unmet dependency, or an internal symbol was forced directly	Enable the public Zephyr feature and inspect its dependencies
CS GPIO not ready	The GPIO controller is disabled, the wrong port is referenced, or the CS entry is invalid	Check the GPIO controller status and the cs-gpios mapping
Pin conflict	The same GPIO is assigned to another peripheral or board function	Compare the schematic, DTS files, overlays, and generated devicetree

When a build-time failure appears, avoid changing the SPI command code. The firmware has not yet reached the point where protocol behavior can be tested.

Layer 2: runtime readiness

Before the first transfer, check the spi_dt_spec:

if (!spi_is_ready_dt(&spi_dev)) {
 LOG_ERR("SPI device not ready");
 return -ENODEV;
}

This verifies that the SPI controller and any CS GPIO described by the spi_dt_spec are ready for use.

If the check fails, verify:

[ ] Is the SPI controller enabled?
[ ] Is the GPIO controller used for CS enabled?
[ ] Is the CS GPIO specification valid?
[ ] Does the child node's reg index match the intended cs-gpios entry?
[ ] Does the final generated devicetree match the expected overlay?
.

Identity and status checks

Similar to checking a known register on an I2C device, create one simple identity or status transaction for each SPI peripheral.

Examples:

Device	Typical check
AFE	Read `CHIP_ID`, for example register `0x0008`
Accelerometer	Read device ID registers
SPI flash	Send `READ ID`, commonly opcode `0x9F`, and compare manufacturer/device ID

The exact command, frame length, dummy-byte requirements, and expected response must come from the peripheral datasheet.

A useful bring-up pattern is:

1. Access only one device.
2. Send its identity or status command.
3. Read the expected number of response bytes.
4. Extract the response from the correct RX offset.
5. Compare it with the expected value.
6. Repeat the transaction many times.
7. Continue with the next device only after the first one is stable.

The application can keep each check in a separate function:

ret = read_accel_id();
if (ret < 0) {
 LOG_ERR("Accelerometer ID read failed: %d", ret);
}

ret = read_flash_id();
if (ret < 0) {
 LOG_ERR("Flash ID read failed: %d", ret);
}

ret = read_afe_chip_id();
if (ret < 0) {
 LOG_ERR("AFE CHIP_ID read failed: %d", ret);
}

Each function should implement the command format required by its own device rather than relying on a generic identity-read transaction.

If the SPI specification is ready and the API call succeeds, verify that the transaction itself matches the peripheral datasheet.

Check:

[ ] Is the command opcode correct?
[ ] Are register addresses sent in the correct order?
[ ] Are read/write bits placed correctly?
[ ] Are all required header bytes included?
[ ] Are dummy bytes included only when the protocol requires them?
[ ] Is the RX response read from the correct offset?
[ ] Does CS remain active across the complete command and response?
[ ] Is the configured SPI mode correct?

A common mistake is to assume that a successful call means that the frame was correct. The SPI controller can successfully transmit a frame that the peripheral doesn’t understand.

Layer 3: electrical behavior

Use an oscilloscope or logic analyzer.

Check:

[ ] CS idles in its inactive state.
[ ] Only the intended CS line becomes active.
[ ] SCK toggles at the expected frequency.
[ ] MOSI carries the expected command bytes.
[ ] MISO changes when the selected peripheral should respond.
[ ] CS remains active for the complete transaction.
[ ] Inactive peripherals release MISO.

If the logic analyzer shows no activity, return to the configuration and runtime-readiness layers.

If the waveforms are present but the data is incorrect, investigate the SPI mode, command format, signal integrity, and peripheral state.

Runtime failure table

Symptom	Likely cause	First steps
`spi_is_ready_dt()` false	Bus or CS GPIO not ready	Inspect the final DTS, GPIO status, CS mapping, pinctrl, and Kconfig
Works at 1 MHz but not 8 MHz	Limits imposed by layout, on signal integrity and drive strength	Reduce the frequency and inspect the waveforms
All reads return `0x00` or `0xFF`	MISO is held low or floating, the device is unpowered, the wrong bytes are being inspected, or the protocol is incorrect	Check power, voltage levels, reset, transaction patterns, MISO waveform, SPI PCB layout
Identity value changes randomly	Frequency is too high, signal integrity is poor, CS timing is unstable, or MISO contention exists	Verify reg against cs-gpios and test devices individually
Only one device works	Incorrect CS mapping, another device is driving MISO, or one peripheral is affecting the shared bus	Check `reg` to `cs-gpios` mapping
Device works after reset only sometimes	Startup timing, power sequencing, reset timing, or incomplete rail discharge	Add proper startup delay and verify rails
Write appears to be ignored	Missing command bytes, an incomplete frame, write protection, or incorrect byte order	Compare exact SPI transaction frame with datasheet

14. Logic analyzer / oscilloscope checks

A logic analyzer is one of the fastest tools for debugging SPI protocol problems. An oscilloscope becomes especially useful when the digital transaction appears correct but communication becomes unreliable at higher frequencies.

For each SPI device, capture at least:

CS
SCK
MOSI
MISO

When several devices share the bus, capturing all CS lines together can also reveal accidental device selection or MISO contention.

What a healthy transaction looks like

For a device with active-low chip select, a typical transaction follows this sequence:

1. CS starts high.
2. CS goes low and selects the device.
3. SCK begins toggling.
4. MOSI carries the command, address, or payload bytes.
5. MISO carries response data during the expected part of the frame.
6. SCK stops toggling.
7. CS returns high.
8. All other CS lines remain high throughout the transaction.

Basic checks

[ ] CS idles in its inactive state.
[ ] The target CS becomes active before SCK starts.
[ ] The target CS remains active for the complete transaction.
[ ] The target CS returns inactive after the final clock edge.
[ ] All other CS lines remain inactive.
[ ] The SCK frequency matches the configured value.
[ ] MOSI carries the expected command and address bytes.
[ ] MISO changes when the selected device is expected to respond.

Check command alignment

SPI is full-duplex. The controller receives one bit for every bit it transmits, even while it is sending command or address bytes.

For example, suppose a device expects a two-byte command followed by a two-byte response, and its protocol requires dummy bytes to generate the response clocks:

TX: command0 command1 dummy0 dummy1
RX: junk0 junk1 data0 data1

The first two received bytes may not contain useful data because they were captured while the command was being transmitted.

In this case, the application must read the response from the correct RX offset:

uint8_t response0 = rx_buf[2];
uint8_t response1 = rx_buf[3];

The exact offset depends on the peripheral’s transaction format. Some devices return data immediately, while others require address bytes, turnaround clocks, or dummy bytes before the response becomes valid.

Don’t assume that the first byte in the RX buffer is the first response byte. Compare the captured frame with the timing diagram in the device datasheet.

Check SPI mode

An incorrect CPOL or CPHA setting can produce responses that look shifted, unstable, or consistently incorrect.

On the logic analyzer, verify:

[ ] The SCK idle level matches the datasheet.
[ ] MOSI changes on the expected clock edge.
[ ] The peripheral samples MOSI on the correct edge.
[ ] MISO becomes valid before the controller's sampling edge.
[ ] Data is not shifted by one bit.

Check MISO contention

When several peripherals share the same SPI bus, only the selected device should drive MISO.

Possible symptoms of MISO contention include:

- distorted or intermediate MISO voltage levels
- unstable identity-register values
- one device working only when another device is disconnected
- responses depending on which device was accessed previously
- communication becoming reliable when the frequency is reduced

Capture the MISO signal together with every CS line.

Verify:

[ ] Only one CS line is active.
[ ] Inactive devices release MISO.
[ ] MISO returns to an idle or high-impedance state after CS becomes inactive.
[ ] No device continues driving MISO after its transaction finishes.

If two CS lines become active simultaneously, correct the CS mapping or GPIO behavior before investigating the command protocol.

Some devices don’t place MISO into a high-impedance state under every operating condition. This should be verified in each peripheral datasheet before placing multiple devices on the same bus.

Check power-gated devices

A powered-off peripheral may still affect the shared SPI bus through its I/O protection structures.

When a device is power-gated, verify:

[ ] It doesn't clamp SCK.
[ ] It doesn't clamp MOSI.
[ ] It doesn't drive or clamp MISO.
[ ] Its CS line remains inactive.
[ ] It isn't being back-powered through I/O pins.

Power-sequencing problems can look exactly like SPI protocol failures. Compare the SPI signals with the peripheral supply and reset signals when the problem occurs during startup or shutdown.

15. An example of a bring-up order for custom boards

The safest bring-up strategy is incremental.

Do not enable every SPI device, interrupt, FIFO, power-management feature, and high-speed transfer at the same time. Each additional feature introduces another possible source of failure.

Instead, begin with the smallest working configuration and add one new variable at a time.

Phase 1: Hardware sanity

[ ] Confirm that all required power rails are present and stable.
[ ] Confirm that the logic voltage is compatible with the nRF5 I/O levels.
[ ] Confirm the state of device power-enable pins, if present.
[ ] Confirm the state of reset pins, if present.
[ ] Wait for the device's required startup time. 
[ ] Confirm that every CS line idles in its inactive state.
[ ] Confirm that the intended SPI signals reach the correct device pins.

Phase 2: Devicetree sanity

[ ] Enable the intended SPI controller node.
[ ] Define pinctrl for SCK, MOSI, and MISO.
[ ] Add the required CS GPIO to the controller's cs-gpios property.
[ ] Enable gpio0 or gpio1 as required.
[ ] Add only one SPI child node.
[ ] Verify that the child node's reg value selects the correct CS entry.
[ ] Set spi-max-frequency to 1 MHz or lower.
[ ] Perform a pristine build.
[ ] Inspect build/zephyr/zephyr.dts.

Phase 3: C-level readiness

[ ] Create one spi_dt_spec using SPI_DT_SPEC_GET().
[ ] Confirm that the selected SPI mode matches the datasheet.
[ ] Confirm that spi_is_ready_dt() returns true.
[ ] Log a clear message when the readiness check passes or fails.

Phase 4: First transaction

[ ] Send one known identity or status command.
[ ] Use the exact frame format described in the datasheet.
[ ] Keep CS active for the complete command and response.
[ ] Include dummy bytes only when the device protocol requires them.
[ ] Read the response from the correct RX offset.
[ ] Check the SPI API return value.
[ ] Repeat the transaction many times.
[ ] Capture CS, SCK, MOSI, and MISO.

Phase 5: Add devices one by one

After the first device is stable, add the remaining SPI peripherals individually. Confirm that identity reads and read status transactions are fine.

Phase 6: Functional tests

[ ] Write one simple configuration register.
[ ] Read the same register back when the device supports readback.
[ ] Configure the basic operating mode.
[ ] Read status registers.
[ ] Test one measurement or data-acquisition path.
[ ] Test FIFO operation if required.
[ ] Test interrupt behavior only after polling works.

Phase 7: Frequency optimization

[ ] Repeat identity reads.
[ ] Repeat register read/write tests.
[ ] Exercise the main data-transfer path.
[ ] Check for intermittent errors.
[ ] Inspect CS, SCK, MOSI, and MISO.
[ ] Check rise time, ringing, overshoot, and sampling margins when needed.

Phase 8: Power management testing

Test:

[ ] Device sleep and wake-up commands.
[ ] MCU sleep and resume behavior.
[ ] Power-gating and power restoration.
[ ] CS state while the device is powered off.
[ ] SPI pin states during low-power modes.
[ ] Startup delays after power restoration.
[ ] Device reinitialization after wake-up.
[ ] Possible back-powering through SPI or GPIO pins.

Phase 9: Production-driver structure

[ ] A device-specific devicetree binding.
[ ] Driver configuration and runtime data structures.
[ ] DEVICE_DT_DEFINE() or a subsystem-specific device macro.
[ ] Kconfig and CMake integration.
[ ] Initialization and readiness checks.
[ ] Concurrency protection for shared state or SPI access.
[ ] Error propagation and recovery.
[ ] Power-management support.
[ ] Automated tests for register and protocol handling.

16. Final checklist before blaming the driver

Use this checklist when the SPI peripheral is not responding and you feel tempted to rewrite the driver.

Work through each category systematically. A failure that appears to come from the driver may instead originate in the devicetree, build configuration, transaction format, PCB, power sequence, or signal integrity.

Devicetree

[ ] Is the intended SPI controller node enabled?
[ ] Are SCK, MOSI, and MISO defined in pinctrl configuration?
[ ] Are the correct pinctrl states referenced by the SPI controller?
[ ] Are the CS pins listed in the controller's cs-gpios property?
[ ] Does each child node use the correct reg index?
[ ] Does each child node's unit address match its reg value?
[ ] Does each spi-max-frequency value use a supported frequency?
[ ] Are gpio0 and gpio1 enabled as required?
[ ] Are interrupt, reset, enable, and busy pins described as GPIOs?
[ ] Does each child compatible match the intended access pattern?
[ ] Does the custom binding allow every property used by the child node?
[ ] Does build/zephyr/zephyr.dts match the schematic and PCB layout?

Kconfig / build

[ ] Is CONFIG_SPI=y enabled?
[ ] Is CONFIG_GPIO=y enabled when CS or auxiliary GPIOs are used?
[ ] Is CONFIG_PINCTRL=y enabled?
[ ] Are the required logging options enabled for debugging?
[ ] Are unnecessary low-level nrfx symbols avoided?
[ ] Is the expected SPI backend enabled in build/zephyr/.config?
[ ] Is the custom driver's Kconfig symbol enabled, if applicable?
[ ] Are all Kconfig dependencies satisfied?
[ ] Is the external Zephyr module included in the build, if applicable?
[ ] Does the build output confirm that the module was detected?
[ ] Was a pristine build performed after devicetree, binding, module, or Kconfig changes?

C access pattern

[ ] Are generic SPI children accessed with SPI_DT_SPEC_GET()?
[ ] Is DEVICE_DT_GET() used only for real driver-backed children?
[ ] Does the driver instantiate the device node when used?
[ ] Is spi_is_ready_dt() checked before transfers?
[ ] Are auxiliary GPIOs checked with gpio_is_ready_dt()?
[ ] Are operation flags correct for the device?
[ ] Is the response copied from the correct RX offset?
[ ] Are return values checked after every SPI call?
[ ] Are transport errors logged separately from unexpected device responses?

SPI protocol

[ ] Is the SPI mode correct?
[ ] Is the bit order correct?
[ ] Is the word size correct?
[ ] Is the configured frequency conservative enough for bring-up?
[ ] Is the command opcode correct?
[ ] Are register addresses transmitted in the required byte order?
[ ] Are read/write indicator bits placed correctly?
[ ] Are all required command and header bytes included?
[ ] Are dummy bytes included only when required by the peripheral?
[ ] Is the expected number of clock pulses generated?
[ ] Does CS remain active for the complete command and response?
[ ] Are command, response, and turnaround timing requirements respected?
[ ] Are writes transmitting the complete frame rather than only the data value?
[ ] Are write-protection, busy, or status conditions handled correctly?

Chip-select behavior

[ ] Does each CS line idle in its inactive state?
[ ] Is the active level consistent with the peripheral datasheet?
[ ] Is the correct CS selected for each child node?
[ ] Does only one CS line become active during a transaction?
[ ] Does CS become active before the first clock edge?
[ ] Does CS remain active until the final clock edge is complete?
[ ] Does CS return inactive after the transaction?
[ ] Are external CS pull-ups present where required?
[ ] Does CS remain inactive during MCU reset and peripheral power sequencing?
[ ] Is software avoiding unnecessary manual CS toggling?

Hardware and power

[ ] Is the peripheral powered at the expected voltage?
[ ] Are the MCU and peripheral logic levels compatible?
[ ] Are all required power rails stable?
[ ] Has the peripheral completed its specified startup time?
[ ] Is the peripheral released from reset?
[ ] Are enable or shutdown pins in the correct state?
[ ] Are the SPI signals connected to the intended package pins?
[ ] Does the PCB net mapping match the devicetree pin mapping?
[ ] Are the physical components correctly placed and soldered?
[ ] Are CS lines held inactive during reset?
[ ] Do inactive devices release MISO?
[ ] Are powered-off devices clamping the shared bus?
[ ] Is any peripheral being back-powered through SPI or GPIO pins?
[ ] Are decoupling and grounding adequate near the peripheral?
[ ] Are traces, connectors, branches, and stubs suitable for the selected frequency?

Shared bus behavior

[ ] Do all devices use compatible I/O voltages?
[ ] Does each device have a dedicated CS line?
[ ] Does each reg value select the intended cs-gpios entry?
[ ] Do inactive peripherals place MISO into a high-impedance state?
[ ] Does communication remain reliable after each additional device is connected?
[ ] Does every previously validated device still work after adding a new one?
[ ] Are power-gated devices isolated appropriately?
[ ] Can the software switch frequency and mode safely for each child device?
[ ] Is the total bus loading acceptable?
[ ] Would a separate SPI bus reduce electrical or timing conflicts?

Interrupts and auxiliary GPIOs

[ ] Are INT, DRDY, BUSY, RESET, and ENABLE treated as GPIO signals?
[ ] Are these properties located in the child device node?
[ ] Does the binding define each custom GPIO property?
[ ] Is the GPIO controller enabled?
[ ] Does gpio_is_ready_dt() succeed?
[ ] Is the GPIO direction configured correctly?
[ ] Is the active level correct?
[ ] Is the interrupt edge or level configuration correct?
[ ] Does the interrupt signal toggle electrically?
[ ] Does the GPIO callback remain short?
[ ] Are SPI transfers deferred to a work item or thread?
[ ] Is the peripheral's interrupt source cleared correctly?

Measurement

[ ] Does the target CS idle inactive?
[ ] Does only the target CS become active?
[ ] Does SCK begin after CS becomes active?
[ ] Does SCK use the expected frequency and idle level?
[ ] Are the expected number of clock cycles present?
[ ] Do MOSI bytes match the intended command frame?
[ ] Does MISO respond during the expected part of the transaction?
[ ] Does the application read the corresponding RX positions?
[ ] Are the logic analyzer's CPOL, CPHA, bit-order, and word-size settings correct? 
[ ] Are signal levels electrically valid?
[ ] Are rise and fall times acceptable?
[ ] Are there signs of ringing, overshoot, or undershoot?
[ ] Are there signs of MISO contention?
[ ] Do power and reset signals remain stable during the transaction?
[ ] Are successful and failing captures visibly different?

The most important question is not:

Why is the driver failing?

It is:

At which layer does the observed behavior
first differ from what is expected?

Once that layer is identified, the number of possible causes becomes much smaller.

🧩 Zephyr SPI Notes for Nordic microcontrollers - Part 2

Mon, 13 Jul 2026 00:00:00 +0000

Practical notes for using SPI on Nordic nRF52 / nRF52840 with Zephyr, especially with multiple devices on one bus and compatible = "nordic,nrf-spim".

In the first part of these notes, the focus was on getting the SPI hardware description right: selecting the Nordic SPIM controller, assigning pins through pinctrl, defining chip-selects, enabling the right Kconfig options, and describing SPI child nodes in devicetree.

That configuration work is essential, but it is only the first half of the story.

Once the SPI bus and its devices are described in devicetree, the C code still has to access them correctly. This is where Zephyr’s devicetree macros, SPI helper APIs, and device model can become confusing, especially when a project mixes manual SPI transactions with driver-backed devices.

This second part focuses on that boundary.

It explains when to use SPI_DT_SPEC_GET(), when SPI_DT_SPEC_INST_GET() makes sense, and why DEVICE_DT_GET() is not a generic way to access any SPI child node. It also explains the common __device_dts_ord_* linker error, which usually appears when the code asks for a Zephyr device object that no compiled driver created.

Finally, this post closes with small SPI transfer helpers for manual bring-up: write-only transfers, full-duplex transfers, command-plus-response transactions, RAM-backed buffers, and the separation between generic SPI helpers and device-specific command wrappers.

The goal is not to build a complete Zephyr driver yet. The goal is to make the first application-level SPI transactions predictable, readable, and easier to debug.

5. Access patterns in C

This section covers two access patterns: manual SPI access and driver-backed device access. It introduces them through three related macros.

Manual SPI access:
- SPI_DT_SPEC_GET()
- SPI_DT_SPEC_INST_GET()

Driver-backed device access:
- DEVICE_DT_GET()

These access patterns belong to Zephyr’s devicetree, SPI and device-model APIs.

Both SPI_DT_SPEC_GET and SPI_DT_SPEC_INST_GET initialize the same type for manual SPI access:

struct spi_dt_spec

while DEVICE_DT_GET obtains a pointer to a created driver, providing driver-backed device access:

struct device

These macros help with static configuration, portability and compile-time generation. However, they are configuration helpers, not memory-safety guarantees.

`SPI_DT_SPEC_GET()`

When manually implementing a peripheral’s command/register protocol, this is usually the correct choice. It provides the robust struct spi_dt_spec initialization as the instance-based macro. More precisely, it accepts a devicetree node identifier.

Macros such as this make it possible to use:

DT_NODELABEL(afe)
DT_ALIAS(my_afe)
DT_PATH(soc, spi_4002f000, afe_0)

Zephyr distinguishes the macros used to obtain a node identifier from the API that consumes it.

By using this macro, this line:

static const struct spi_dt_spec spi_afe = SPI_DT_SPEC_GET(SPI_NODE_AFE, SPI_OP);

collects the SPI information for the child node:

Which SPI bus the child belongs to
Which chip-select index it uses
Which chip-select configuration corresponds to that index, including the GPIO when chip-select is GPIO-controlled.
The child device frequency from spi-max-frequency
The SPI operation flags from SPI_OP

Example:

#include <zephyr/device.h>
#include <zephyr/drivers/spi.h>
#include <zephyr/drivers/pinctrl.h>
#include <zephyr/kernel.h>
#include <zephyr/logging/log.h>

LOG_MODULE_REGISTER(app, LOG_LEVEL_INF);

#define SPI_NODE_ACC DT_NODELABEL(acc)
#define SPI_NODE_FLASH DT_NODELABEL(flash)
#define SPI_NODE_AFE DT_NODELABEL(afe)
#define SPIOP (SPI_WORD_SET(8) | SPI_TRANSFER_MSB | SPI_OP_MODE_MASTER)

static const struct spi_dt_spec spi_acc = SPI_DT_SPEC_GET(SPI_NODE_ACC, SPIOP);
static const struct spi_dt_spec spi_flash = SPI_DT_SPEC_GET(SPI_NODE_FLASH, SPIOP);
static const struct spi_dt_spec spi_afe = SPI_DT_SPEC_GET(SPI_NODE_AFE, SPIOP);

int main(void)
{
 if (!device_is_ready_dt(&spi_acc) || !device_is_ready_dt(&spi_flash)
 || !device_is_ready_dt(&spi_afe))
 {
 LOG_ERR("One or more SPI access paths are not ready");
 return -ENODEV;
 }

 LOG_INF("SPI buses and chip-select controllers are ready");

 while (1) {
 k_sleep(K_SECONDS(1));
 }
}

Historically, the SPI acquisition macros accepted three parameters, with the final argument representing a chip-select timing delay in microseconds. In , providing a third argument to SPI_DT_SPEC_GET or SPI_DT_SPEC_INST_GET is deprecated and triggers build errors or compile-time warnings depending on the compiler configuration.

For the devicetree-based SPI helper macros, chip-select setup and hold timing now belong in devicetree rather than in the macro arguments. These timing figures should be specified through the standardized devicetree properties spi-cs-setup-delay-ns and spi-cs-hold-delay-ns.

`SPI_DT_SPEC_INST_GET()`

SPI_DT_SPEC_INST_GET() initializes an SPI specification for a numbered instance of DT_DRV_COMPAT. Drivers commonly combine it with DT_INST_FOREACH_STATUS_OKAY() and DEVICE_DT_INST_DEFINE() to create one driver-backed device for every enabled compatible node.

The preprocessor translates these abstractions during early compilation phases:

Resolution of instance to node: The preprocessor evaluates SPI_DT_SPEC_INST_GET(inst, ...) by replacing the instance index with a call to DT_DRV_INST(inst)
Expression to node identifier: DT_DRV_INST(inst) expands into the internal devicetree node path token.
Structure initialization: This token is passed to SPI_DT_SPEC_GET, which queries the generated devicetree header files to output a static initializer for a struct spi_dt_spec

To enable instance-based macros within a driver, the compilation unit must define the compatible token corresponding to the binding’s compatible string.

#define DT_DRV_COMPAT manufacturer_reference

Example:

, updated to Zephyr 4.3:

#define DT_DRV_COMPAT cormoran_pmw3610

#define PMW3610_DEFINE(n) \
 static struct pixart_data data##n; \
 static const struct pixart_config config##n = { \
 .spi = SPI_DT_SPEC_INST_GET(n, PMW3610_SPI_MODE), \
 .irq_gpio = GPIO_DT_SPEC_INST_GET(n, irq_gpios), \
 .cpi = DT_PROP(DT_DRV_INST(n), cpi), \
 .swap_xy = DT_PROP(DT_DRV_INST(n), swap_xy), \
 .inv_x = DT_PROP(DT_DRV_INST(n), invert_x), \
 .inv_y = DT_PROP(DT_DRV_INST(n), invert_y), \
 .evt_type = DT_PROP(DT_DRV_INST(n), evt_type), \
 .x_input_code = DT_PROP(DT_DRV_INST(n), x_input_code), \
 .y_input_code = DT_PROP(DT_DRV_INST(n), y_input_code), \
 .force_awake = DT_PROP(DT_DRV_INST(n), force_awake), \
 .force_awake_4ms_mode = DT_PROP(DT_DRV_INST(n), force_awake_4ms_mode), \
 }; \
 DEVICE_DT_INST_DEFINE(n, pmw3610_init, NULL, &data##n, &config##n, POST_KERNEL, \
 CONFIG_INPUT_PMW3610_INIT_PRIORITY, &pmw3610_driver_api);

 DT_INST_FOREACH_STATUS_OKAY(PMW3610_DEFINE)

`DEVICE_DT_GET()`

This macro is used when code needs a reference to a driver-created Zephyr device object. It expands to a pointer to the device object created for that node.

The device may not have initialized successfully, which is why you subsequently call:

device_is_ready(dev)

Then, the application can use functions such as sensor_sample_fetch() or flash_read(), through the corresponding subsystem API.

Using the SPI controller directly is also possible:

const struct device *bus = DEVICE_DT_GET(DT_NODELABEL(spi3));

However, obtaining the controller pointer is only part of the manual SPI API. The caller must also construct and pass a struct spi_config to functions such as:

spi_transceive(bus, &config, &tx, &rx);

SPI_DT_SPEC_GET() is usually more convenient because it packages the bus pointer and the child-specific frequency, chip-select, and operation configuration into one struct spi_dt_spec.

Example using a

#include <zephyr/kernel.h>
#include <zephyr/device.h>
#include <zephyr/devicetree.h>
#include <zephyr/drivers/sensor.h>

#define BME280 DT_INST(0, bosch_bme280)
// Note that DT_INST is less explicit than DT_ALIAS or DT_NODELABEL
// Instance numbering is based on compatible instances rather
// than the physical SPI chip-select number

#if !DT_NODE_HAS_STATUS(BME280, okay)
#error Your devicetree has no enabled nodes with compatible "bosch,bme280"
#endif

const struct device *dev = DEVICE_DT_GET(BME280);

int main(void){
 if (!device_is_ready(dev)){
 printk("No device \"%s\" found; did initialization fail?\n",
 dev->name);
 return -ENODEV;
 }
 else{
 printk("Found device \"%s\"\n", dev->name);
 }
}

Definition of a hardware binding

A binding is required; a driver is optional. A matching binding doesn’t create a struct device by itself. A driver must instantiate the node with a device-definition macro such as DEVICE_DT_INST_DEFINE().

The current Zephyr device-model documentation confirms that DEVICE_DT_GET() only works when a device object was allocated for the node; otherwise, the reference fails at link time.

A small binding for the real device is the clean solution:

# dts/bindings/sensor/manufacturer,device.yaml

description: |
 Optical analog front end accessed through application-managed SPI transactions

compatible: "manufacturer,reference"

include: [sensor-device.yaml, spi-device.yaml]

properties:
 reg:
 required: true
 spi-max-frequency:
 type: int
 required: true
 description: Max SPI clock in Hz (up to 80000000)

 # These properties are optional
 int1-gpios:
 type: phandle-array
 required: false
 description: Optional interrupt GPIO connected to the sensor’s INT1 pin

 reset-gpios:
 type: phandle-array
 required: false
 description: Optional reset GPIO

Bindings validate nodes and generate the property macros consumed by the C devicetree API.

For a binding and manual application-level SPI access, you’ll usually need to modify:

app.overlay (if devicetree won't be modified)
dts/bindings/sensor/manufacturer,device.yaml
CMakeLists.txt
src/main.c
prj.conf/defconfig

When you add a complete driver, you’ll normally also need to either create or modify:

drivers/sensor/device.c
drivers/sensor/CMakeLists.txt
drivers/sensor/Kconfig

DEVICE_DT_INST_DEFINE(...)

A west manifest becomes relevant when the driver is maintained as a separate external repository or Zephyr module. It’s not a normal requirement for an application-local binding. Zephyr modules can expose additional DTS roots through their module metadata.

SPI Operating modes

Mode	CPOL	CPHA	DTS Properties
0	0	0	(default)
1	0	1	`spi-cpha`
2	1	0	`spi-cpol`
3	1	1	`spi-cpol; spi-cpha`

For fixed peripheral characteristics, the cleanest approach is usually adding these properties to devicetree:

afe: optical-afe@2 {
 spi-cpol;
 spi-cpha;
};

Operation Flags

Common flags for spi_config.operation:

Flag	Description
`SPI_OP_MODE_MASTER`	Controller/master mode (default)
`SPI_OP_MODE_SLAVE`	Peripheral/slave mode
`SPI_MODE_CPOL`	Clock polarity (idle high)
`SPI_MODE_CPHA`	Clock phase (sample on second edge)
`SPI_WORD_SET(n)`	Word size in bits (typically 8)
`SPI_TRANSFER_MSB`	MSB first (default)
`SPI_TRANSFER_LSB`	LSB first
`SPI_HOLD_ON_CS`	Keep CS active after transaction
`SPI_LOCK_ON`	Lock bus for multiple transactions
`SPI_CS_ACTIVE_HIGH`	CS is active high (unusual)

If using SPI_LOCK_ON or SPI_HOLD_ON_CS, release when done:

spi_release_dt(&spi_dev);

SPI_HOLD_ON_CS attempts to leave CS asserted after a transfer, and SPI_LOCK_ON prevents other callers from acquiring the controller until released. They should be used cautiously on a bus shared by several devices.

A common starting point when working with SPI peripherals is:

#define SPI_OP \
(SPI_OP_MODE_MASTER | SPI_WORD_SET(8) | SPI_TRANSFER_MSB)

This means:

SPI_OP_MODE_MASTER -> The nRF52840 initiates the transfer and drives SCK
SPI_WORD_SET(8) -> 8-bit words
SPI_TRANSFER_MSB -> most significant bit first

If the device requires another SPI mode, add CPOL and/or CPHA flags:

#define SPI_OP_MODE3 \
(SPI_OP_MODE_MASTER | SPI_WORD_SET(8) | SPI_TRANSFER_MSB | \
 SPI_MODE_CPOL | SPI_MODE_CPHA)

Don’t assume all SPI devices on the same bus use the same mode. Check each datasheet.

Different operation flags per device

If needed, give each device its own operation flags:

#define ACC_SPI_OP \
 (SPI_OP_MODE_MASTER | SPI_WORD_SET(8) | SPI_TRANSFER_LSB)

#define FLASH_SPI_OP \
 (SPI_OP_MODE_MASTER | SPI_WORD_SET(8) | SPI_TRANSFER_MSB | \
 SPI_MODE_CPOL | SPI_MODE_CPHA)

#define AFE_SPI_OP \
(SPI_OP_MODE_MASTER | SPI_WORD_SET(8) | SPI_TRANSFER_MSB)

static const struct spi_dt_spec spi_acc = SPI_DT_SPEC_GET(SPI_NODE_ACC, ACC_SPI_OP);
static const struct spi_dt_spec spi_flash = SPI_DT_SPEC_GET(SPI_NODE_FLASH, FLASH_SPI_OP);
static const struct spi_dt_spec spi_afe = SPI_DT_SPEC_GET(SPI_NODE_AFE, AFE_SPI_OP);

This keeps the code ready for devices that later need different CPOL, CPHA, word size, or transfer behavior.

Manually adding CPOL and CPHA flags in C is valid, but the code should follow one primary convention and use it consistently.

6. `__device_dts_ord_*`: what the error really means

A linker error like this:

undefined reference to `__device_dts_ord_...'

doesn’t always mean that the devicetree node is missing.

More precisely, it means:

The C code asked Zephyr for a device object,
but no compiled driver created that device object.

A common trigger is, for example:

const struct device *dev = DEVICE_DT_GET(DT_NODELABEL(radio1));

This only works if radio1 is a real Zephyr device instance, backed by:

- a valid devicetree node
- status = "okay"
- a compatible string with a matching binding
- a compiled driver
- and the Kconfig symbols needed to include that driver

If any of those pieces are inconsistent, the devicetree node may appear in zephyr.dts, but the linker can still fail with __device_dts_ord_*.

For solving this issue, there are two different questions to answer:

1. Does the node exist in devicetree?
2. Did a driver create a Zephyr struct device for that node?

DT_NODELABEL(radio1) can be valid while DEVICE_DT_GET(DT_NODELABEL(radio1)) still fails.

Why this error happens

In SPI bring-ups, this type of issue appears because several configuration layers must agree with each other:

- .dts / .dtsi describe the hardware
- bindings define which properties are legal for each compatible
- prj.conf / defconfig select software features and drivers
- C code chooses either DEVICE_DT_GET() or SPI_DT_SPEC_GET()

When those layers contradict each other, Zephyr may generate a devicetree that looks plausible, but the final device object is still missing.

Case 1: Generic SPI child accessed as a real device

This pattern is unsafe for a generic SPI child:

afe: optical-afe@2 {
 compatible = "vnd,spi-device";
 reg = <2>;
 spi-max-frequency = <1000000>;
};

const struct device *dev = DEVICE_DT_GET(DT_NODELABEL(afe));

The node exists, but there isn’t a dedicated Zephyr driver creating a struct device for it.

For manual SPI transactions, use:

#include <zephyr/drivers/spi.h>

#define AFE_NODE DT_NODELABEL(afe)
#define AFE_SPI_OP \
(SPI_OP_MODE_MASTER | SPI_WORD_SET(8) | SPI_TRANSFER_MSB)

static const struct spi_dt_spec spi_afe = SPI_DT_SPEC_GET(AFE_NODE, AFE_SPI_OP);

Then check:

if (!spi_is_ready_dt(&spi_afe)) {
 return -ENODEV;
}

In Zephyr versions where "vnd,spi-device" works, the matching binding is found under the test bindings:

zephyr/dts/bindings/test/vnd,spi-device.yaml

That binding includes the common spi-device.yaml properties required by macros such as SPI_DT_SPEC_GET().

However, vnd,spi-device is not a wildcard compatible and doesn’t mean “any SPI peripheral”. Devicetree compatibles are matched against bindings by their exact strings. Here, vnd is only a placeholder vendor prefix and the matching binding exists for Zephyr’s internal tests, not as a production description of arbitrary SPI hardware.

Why `SPI_DT_SPEC_GET()` is different

SPI_DT_SPEC_GET() doesn’t require the SPI child to have its own full driver.

It creates an SPI access descriptor from the child node, using the hardware description provided by the binding:

- bus device
- SPI frequency
- chip-select information
- SPI operation flags

However, the SPI bus itself still needs a real driver.

So this can work:

static const struct spi_dt_spec spi_afe = SPI_DT_SPEC_GET(DT_NODELABEL(afe), AFE_SPI_OP);

because the actual Zephyr device object being required is the SPI controller, such as &spi3, not a full dedicated driver for the SPI child.

Case 2: The SPI bus or GPIO controllers weren’t fully enabled

Another issue can be solved by explicitly enabling the GPIO-related nodes in devicetree:

&gpio0 {
 status = "okay";
};

&gpio1 {
 status = "okay";
};

&gpiote {
 status = "okay";
};

This matters because some SPI children use GPIO chip-selects, interrupt pins, or both.

The SPI bus may look correct, but chip-select and interrupt handling can still depend on the GPIO controller nodes being available.

For SPI with cs-gpios, this means the hardware description must include both the SPI controller configuration:

&spi3 {
 status = "okay";
 compatible = "nordic,nrf-spim";
 cs-gpios = <&gpio0 17 GPIO_ACTIVE_LOW>,
 <&gpio0 15 GPIO_ACTIVE_LOW>, 
 <&gpio0 13 GPIO_ACTIVE_LOW>;
};

and the GPIO controller configuration:

&gpio0 {
 status = "okay";
};

&gpio1 {
 status = "okay";
};

If a chip-select pin references &gpio0 or &gpio1, that GPIO controller must be usable.

Case 3: Forcing the wrong Kconfig symbols

One project trap is trying to force low-level nrfx symbols directly, especially:

CONFIG_NRFX_GPIOTE=y

That’s the wrong level of control. It’s better to:

Enable the Zephyr feature you need.
Let Zephyr/NCS select the low-level nrfx backend when possible.

For SPI bring-up, start with:

CONFIG_SPI=y
CONFIG_GPIO=y
CONFIG_PINCTRL=y
CONFIG_LOG=y

If GPIO interrupts are needed later, enable the Zephyr-facing GPIO and interrupt features, then describe the interrupt pin in devicetree or in the custom binding. Don’t blindly force internal nrfx symbols.

7. Basic SPI transmit / receive helpers

After creating a struct spi_dt_spec with SPI_DT_SPEC_GET(), the next step is to perform simple SPI transfers.

For manual bring-up, keep the helpers small and predictable:

- One helper for write-only transfers
- One helper for full-duplex transfers
- One helper for command + response in one CS window

These helpers aren’t device drivers. They only move bytes over SPI.

Device-specific details such as register headers, opcodes, read bits, dummy bytes, and byte order should be handled by device-specific wrapper functions.

Dummy bytes depend on the peripheral. Some devices return useful data during the same bytes used to send a command. Others ignore the first received byte and return valid data only after the command or register address has been shifted in. Some devices also require one or more extra clock cycles before the response becomes valid.

When dummy bytes are needed, they aren’t meaningful commands. They are bytes sent on MOSI so that the SPI controller continues generating SCK pulses while the peripheral shifts out the response on MISO.

Write-only transaction

Use this when the peripheral only needs bytes on MOSI and the MISO response is irrelevant.

static int spi_write_bytes(const struct spi_dt_spec *spi,
 const uint8_t *tx_data,
 size_t tx_len)
{
 const struct spi_buf tx_buf = {
 .buf = (void *)tx_data,
 .len = tx_len,
 };

 const struct spi_buf_set tx = {
 .buffers = &tx_buf,
 .count = 1,
 };

 return spi_write_dt(spi, &tx);
}

Typical use:

// Example: write-enable command for some flash devices
uint8_t cmd[] = { 0x06 };

ret = spi_write_bytes(&spi_flash, cmd, sizeof(cmd));

if (ret != 0) {\
 LOG_ERR("SPI write failed: %d", ret);
}

Full-duplex transceive

SPI is normally full-duplex. Every byte clocked out on MOSI also clocks one byte in on MISO.

Use this helper when the transmit and receive lengths are the same:

static int spi_transceive_bytes(const struct spi_dt_spec *spi,
 const uint8_t *tx_data,
 uint8_t *rx_data,
 size_t len)
{
 const struct spi_buf tx_buf = {
 .buf = (void *)tx_data,
 .len = len,
 };

 struct spi_buf rx_buf = {
 .buf = rx_data,
 .len = len,
 };

 const struct spi_buf_set tx = {
 .buffers = &tx_buf,
 .count = 1,
 };

 const struct spi_buf_set rx = {
 .buffers = &rx_buf,
 .count = 1,
 };

 return spi_transceive_dt(spi, &tx, &rx);
}

Example:

uint8_t tx[2] = { 0x00, 0x00 };
uint8_t rx[2] = { 0 };

ret = spi_transceive_bytes(&spi_acc, tx, rx, sizeof(tx));
if (ret != 0) {
 LOG_ERR("SPI transceive failed: %d", ret);
}

SPI is electrically full-duplex, but Zephyr lets the software describe different amounts of data to transmit and receive.

spi_transceive_dt() is just the devicetree wrapper around:

spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs)

The API accepts independent TX and RX buffer sets, and either one may even be NULL if that direction isn’t used.

For some peripherals, extra transmitted bytes can safely act as dummy bytes while the device shifts out a response. For others, extra bytes may be interpreted as additional commands or data. The datasheet should define which transaction pattern is valid.

Write command, then read response in one CS window

Many SPI devices require this shape:

CS low
send command/header bytes
send dummy bytes to generate additional clock cycles (if any)
read response bytes on MISO
CS high

This must happen as one SPI transaction if the device expects CS to remain asserted.

static int spi_cmd_read(const struct spi_dt_spec *spi,
 const uint8_t *cmd,
 size_t cmd_len,
 uint8_t *response,
 size_t response_len)
{
 uint8_t tx_buf_storage[32] = {0};
 uint8_t rx_buf_storage[32] = {0};

 if ((cmd_len + response_len) > sizeof(tx_buf_storage)) {
 return -EINVAL;
 }

 memcpy(tx_buf_storage, cmd, cmd_len);

 const size_t total_len = cmd_len + response_len;

 const struct spi_buf tx_buf = {
 .buf = tx_buf_storage,
 .len = total_len,
 };

 struct spi_buf rx_buf = {
 .buf = rx_buf_storage,
 .len = total_len,
 };

 const struct spi_buf_set tx = {
 .buffers = &tx_buf,
 .count = 1,
 };

 const struct spi_buf_set rx = {
 .buffers = &rx_buf,
 .count = 1,
 };

 int ret = spi_transceive_dt(spi, &tx, &rx);
 if (ret != 0) {
 return ret;
 }

 memcpy(response, &rx_buf_storage[cmd_len], response_len);
 return 0;
}

RAM-backed buffers are the safest bring-up pattern

For nRF52840 with nordic,nrf-spim, the SPI master uses EasyDMA. Zephyr’s Nordic SPIM binding describes nordic,nrf-spim as the Nordic SPI master with EasyDMA.

During bring-up, prefer RAM-backed buffers:

uint8_t tx_buf[8] = {0};
uint8_t rx_buf[8] = {0};

or:

static uint8_t tx_buf[32];
static uint8_t rx_buf[32];

During bring-up, prefer simple RAM-backed buffers whose lifetime is obvious. Stack buffers are fine for synchronous SPI calls, and static buffers are also safe. Avoid making the first SPI tests depend on pointers to temporary data, returned local arrays, heap allocations, or constant data that may be placed in flash instead of RAM.

Device-specific wrappers should build the command

The generic helper shouldn’t know what a specific device command means.

Better structure:

generic SPI helper:
    "send these bytes and receive these bytes"

device wrapper:
    "build the command format required by this chip"

For example:

static int afe_read_raw(const struct spi_dt_spec *spi,
 const uint8_t *cmd,
 size_t cmd_len,
 uint8_t *data,
 size_t data_len){
 return spi_cmd_read(spi, cmd, cmd_len, data, data_len);
}

Then the AFE-specific code is responsible for building the correct command/header bytes.

This matters because some devices don’t just require a 16-bit register value. The SPI transaction may need to include device-specific command/header bytes, register address bytes, and data bytes.

So avoid code that does this:

uint8_t tx[] = {
 value_msb,
 value_lsb,
};

when the device actually expects something closer to:

command/header bytes + register address bytes + data bytes

The exact byte layout belongs in in device-specific wrapper functions, not in the generic SPI helper.

Example: identity read shape

Most bring-up reads have this form:

uint8_t cmd[] = {/* device-specific read command/header bytes */};
uint8_t id[2] = {0};

ret = spi_cmd_read(&spi_afe, cmd, sizeof(cmd), id, sizeof(id));

if (ret != 0) {
 LOG_ERR("AFE ID read failed: %d", ret);
}
else {
 LOG_INF("AFE ID bytes: 0x%02x 0x%02x", id[0], id[1]);
}

The key point is not the placeholder command. The key point is the transaction shape:

one CS assertion
command/header first
dummy clocks next, if needed
response copied after command bytes

Example: write-register shape

A write-register wrapper may look like this:

static int device_write_register_raw(const struct spi_dt_spec *spi,
 const uint8_t *frame,
 size_t frame_len){
 return spi_write_bytes(spi, frame, frame_len);
}

The caller builds the complete frame:

uint8_t frame[] = {
 /* command/header bytes */
 /* register address bytes */
 /* data bytes */
};

ret = device_write_register_raw(&spi_afe, frame, sizeof(frame));

For complex devices, the frame must include the command/header bytes required by the datasheet.

🧩 Zephyr SPI Notes for Nordic microcontrollers - Part 1

Wed, 24 Jun 2026 00:00:00 +0000

A hardware-first introduction to Zephyr SPI bring-up, focused on the definitions that must be correct before a device can respond.

At the electrical level, the SPI communication protocol looks straightforward: clock, data out, data in, and one chip-select per device.

In Zephyr RTOS, when an SPI device doesn’t respond, it’s tempting to blame the driver or the SPI API.

More often than not, especially on a custom board, SPI issues lie earlier: the wrong controller instance, an unassigned pin, a misplaced compatible string, an incorrect chip-select index, or a configuration detail that was assumed rather than verified.

In Zephyr, an SPI connection is described and enabled across several configuration mechanisms: devicetree defines the hardware and its boot-time configuration, pinctrl assigns peripheral signals to physical pins, and Kconfig enables the software support included in the firmware.

One of the most useful distinctions I have learned in Zephyr is that an SPI bus and the devices connected to it aren’t described in the same way.

The Nordic SPIM peripheral is the controller that represents the bus. Sensors, radios, converters, and other peripherals are child nodes on that bus. Their chip-selects, interrupts, pin assignments, and driver support are configured through related Zephyr definitions, but each belongs to a different node, parent-child relationship, or configuration label.

This is the first part of my Zephyr SPI learning notes. This post explores that separation through SPI configuration on the nRF52840, starting with devicetree, pinctrl, and prj.conf.

1. Mental model: bus and devices

In Zephyr devicetree, an SPI setup has two levels. The bus is the SPI controller node, and the devices connected to that bus are the SPI child nodes.

For instance, if an nRF52840 microcontroller is the SPI master, then other devices are SPI slaves connected to the same physical bus lines:

-> SCK
-> MOSI shared by all SPI devices
-> MISO shared by all SPI devices MISO
-> one separate chip-select per device

The important devicetree idea is:

&spi0 / &spi1 / &spi2 / &spi3
-> SPI controller / bus compatible = "nordic,nrf-spim"
-> belongs to the Nordic SPI controller

cs-gpios
-> belong to the bus, as an array

device1@0 / device2@1 / device3@2 / ...
-> SPI child devices, reg = <0>, <1>, <2>, ...
-> index into the cs-gpios array

So, reg doesn’t mean an SPI address. SPI doesn’t have I2C-style addresses. In this context, reg = <0> means: use entry 0 of the cs-gpios array.

RAK Wisblock example

&spi1 {
 compatible = "nordic,nrf-spi";
 status = "okay";
 cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
 pinctrl-0 = <&spi1_default>;
 pinctrl-1 = <&spi1_sleep>;
 pinctrl-names = "default", "sleep";
 lora: lora@0 {
 compatible = "semtech,sx1262";
 reg = <0>;
 reset-gpios = <&gpio1 6 GPIO_ACTIVE_LOW>;
 busy-gpios = <&gpio1 14 GPIO_ACTIVE_HIGH>;
 tx-enable-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>;
 rx-enable-gpios = <&gpio1 5 GPIO_ACTIVE_LOW>;
 dio1-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>;
 dio2-tx-enable;
 dio3-tcxo-voltage = <SX126X_DIO3_TCXO_3V3>;
 tcxo-power-startup-delay-ms = <5>;
 spi-max-frequency = <1000000>;
 };
};

&gpio0 {
 status = "okay";
}; 

&gpio1 {
 status = "okay";
};

Don’t put the Nordic SPI compatible in child nodes

Correct:

&spi3 {
 compatible = "nordic,nrf-spim";
 device3: optical-afe@2 {
 compatible = "vnd,spi-device";
 reg = <2>; 
 };
};

Incorrect:

device3: optical-afe@2 { 
 compatible = "nordic,nrf-spim"; // wrong 
 reg = <2>;
};

nordic,nrf-spim describes the nRF52840 SPI master peripheral. It doesn’t describe the connected devices.

Generic child vs. real driver child

During early bring-up, it’s acceptable to use a generic SPI child:

compatible = "vnd,spi-device";

That means: “Zephyr, please describe this SPI connection, but my application code will manually send the SPI commands.”

Later, if you write a real Zephyr driver and binding for the device, the child may use a real compatible string:

compatible = "manufacturer,device";

At that point, the child is not only an SPI connection. It becomes a real Zephyr device instance backed by a driver.

Interrupt pins are separate from SPI

Some SPI devices also have interrupt pins. For example, many sensors may use an interrupt line to tell the MCU that data is ready.

That interrupt isn’t part of the SPI bus. It is a normal GPIO property of the child device:

device3: optical-afe@2 {
 compatible = "vnd,spi-device";
 reg = <2>;
 spi-max-frequency = <24000000>;
 int1-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>;
};

This only works cleanly when the binding used by that child node allows the interrupt property. For a generic bring-up node, keep only the properties accepted by the binding. For a proper custom driver, define the property in a custom binding such as manufacturer,device.yaml.

2. `nordic,nrf-spim` vs `nordic,nrf-spi`

On nRF52840 and newer microcontrollers, prefer:

compatible = "nordic,nrf-spim";

SPIM is the EasyDMA-capable SPI master peripheral. It is the typical choice for production SPI transfers.

Conceptually:

Compatible	Meaning	Typical use
`nordic,nrf-spim`	SPI master with EasyDMA	Preferred for nRF52840 SPI buses
`nordic,nrf-spi`	Older/non-DMA SPI master style	Rarely preferred unless required by board/peripheral constraints

SPIM is usually the right choice because:

- It supports EasyDMA transfers.
- It reduces CPU involvement during SPI transfers.
- It's the normal Nordic peripheral style used for higher-throughput SPI.
- It's better suited for repeated register transfers.

Important EasyDMA consequence

Because SPIM uses EasyDMA, SPI transfer buffers should live in RAM.

Good patterns:

uint8_t tx_buf[4] = { 0 };
uint8_t rx_buf[4] = { 0 };

static uint8_t tx_buf[16];
static uint8_t rx_buf[16];

Be careful with buffers that may be placed in flash/ROM, especially constant transmit buffers. If a low-level nrfx SPIM transfer receives a buffer address that is not accessible by EasyDMA, the transfer can fail.

For simple Zephyr application code, stack or static RAM buffers are usually the safest bring-up choice.

Instance choice matters for speed

On nRF52840, not every SPIM instance has the same capabilities.

A conservative rule for custom boards is:

For low-speed bring-up:
    almost any available SPIM instance can work.

For higher-speed SPI:
    prefer the high-speed-capable SPIM instance.

In practice, when using frequencies above 8 MHz, pay attention to the selected SPI instance. This is especially relevant if the devicetree uses something like:

&spi3 {
 compatible = "nordic,nrf-spim";
 status = "okay";
};

spi3 / SPIM3 is commonly the instance used when higher SPI speeds are needed on nRF52840.

However, don’t start bring-up at the maximum frequency. First probe the bus at a slow frequency, then increase speed only after identity reads and signal quality are stable.

3. Pinctrl pattern for nRF52840 SPI

In Zephyr, SPI pin assignment for Nordic nRF52 devices is usually done with pinctrl.

The SPI bus node references pinctrl states:

&spi3 {
 status = "okay";
 compatible = "nordic,nrf-spim";
 pinctrl-0 = <&spi3_default>;
 pinctrl-1 = <&spi3_sleep>;
 pinctrl-names = "default", "sleep"; 
 # cs-gpios and child devices here
};

The actual pin assignment is defined under &pinctrl:

A typical pinctrl definition looks like this:

&pinctrl {
 spi3_default: spi3_default {
 group1 { 
 psels = <NRF_PSEL(SPIM_SCK, 0, 19)>,  # P0.19 
 <NRF_PSEL(SPIM_MOSI, 0, 21)>, # P0.21
 <NRF_PSEL(SPIM_MISO, 0, 23)>; # P0.23 
 };
 };
 spi3_sleep: spi3_sleep {
 group1 { 
 psels = <NRF_PSEL(SPIM_SCK, 0, 19)>, 
 <NRF_PSEL(SPIM_MOSI, 0, 21)>, 
 <NRF_PSEL(SPIM_MISO, 0, 23)>; 
 low-power-enable; 
 }; 
 }; 
};

Meaning of `NRF_PSEL()`

The Nordic pinctrl macro has this practical meaning:

NRF_PSEL(function, port, pin)

For example:

NRF_PSEL(SPIM_SCK, 0, 19)

means:

Route SPIM SCK to P0.19

And:

NRF_PSEL(SPIM_MOSI, 1, 10)

means:

Route SPIM MOSI to P1.10

On nRF52840, valid GPIO ports are:

Port 0 -> P0.xx -> &gpio0
Port 1 -> P1.xx -> &gpio1

There is no P2 on nRF52840.

Pinctrl is for SCK, MOSI, and MISO

For a normal SPI master bus, pinctrl describes the peripheral-controlled SPI signals:

SCK
MOSI
MISO

Chip-select pins are usually described separately with cs-gpios in the SPI bus node:

&spi3 {
 cs-gpios = <&gpio0 17 GPIO_ACTIVE_LOW>, 
 <&gpio0 15 GPIO_ACTIVE_LOW>,
 <&gpio0 13 GPIO_ACTIVE_LOW>;
};

So the usual split is:

pinctrl -> SCK, MOSI, MISO
cs-gpios -> chip-select GPIOs

This is important because CS is often handled as a GPIO by Zephyr, not as one of the NRF_PSEL() entries.

Default state vs. sleep state

The default state is used when the SPI peripheral is active:

pinctrl-0 = <&spi3_default>;
pinctrl-names = "default";

The sleep state is used when the peripheral enters a lower-power state:

pinctrl-1 = <&spi3_sleep>;
pinctrl-names = "default", "sleep";

For battery-powered boards , it is good practice to define both states:

spi3_sleep: spi3_sleep {
 group1 {
 psels = <NRF_PSEL(SPIM_SCK, 0, 19)>,
 <NRF_PSEL(SPIM_MOSI, 0, 21)>,
 <NRF_PSEL(SPIM_MISO, 0, 23)>; 
 low-power-enable; 
 };
};

This helps avoid leaving peripheral pins unnecessarily driven when the SPI bus isn’t being used.

4. `prj.conf` / Kconfig checklist

For a basic SPI application on nRF52840 with GPIO chip-selects, start with the application-level options:

CONFIG_SPI=y
CONFIG_GPIO=y
CONFIG_PINCTRL=y

These are the most important symbols for custom boards patterns:

SPI API -> CONFIG_SPI
GPIO chip-select -> CONFIG_GPIO
Nordic pinctrl -> CONFIG_PINCTRL

For Nordic nrfx-backed SPI:

CONFIG_SPI_NRFX=y

In many nRF Connect SDK / Zephyr configurations, this is selected automatically when:

- the SoC family is Nordic nRF
- CONFIG_SPI=y is enabled
- and an enabled SPI controller exists in devicetree

So the practical rule is:

Enable the subsystem you use.
Let Zephyr select the low-level backend when possible.

Minimal `prj.conf` for manual SPI bring-up

For early custom board SPI testing, a minimal prj.conf can be:

CONFIG_SPI=y
CONFIG_GPIO=y
CONFIG_PINCTRL=y
CONFIG_LOG=y

CONFIG_LOG=y is optional, but useful during bring-up because it lets you print clear status messages such as:

SPI bus ready
Device 3 CHIP_ID read OK
Device 2 identity read failed
Device 1 READ_ID returned 0xFF

Optional: more logging detail

If you want more verbose logs during board bring-up:

CONFIG_LOG=y
CONFIG_LOG_DEFAULT_LEVEL=3

Common levels:

0 -> off
1 -> error
2 -> warning
3 -> info
4 -> debug

For normal bring-up, CONFIG_LOG_DEFAULT_LEVEL=3 is usually enough.

Don’t blindly force nrfx instance symbols

You may find examples using symbols such as:

CONFIG_NRFX_SPIM=y
CONFIG_NRFX_SPIM1=y # or...
CONFIG_NRFX_SPIM3=y

Don’t add these blindly: CONFIG_NRFX_SPIM1, CONFIG_NRFX_SPIM3, and so on.

Depending on the Zephyr / NCS version, board, SoC, and devicetree configuration, these may be selected automatically. If the SPI node is enabled correctly in devicetree, the build system often selects the needed lower-level driver support.

Prefer fixing the devicetree first:

&spi3 {
 status = "okay";
 compatible = "nordic,nrf-spim";
 pinctrl-0 = <&spi3_default>;
 pinctrl-1 = <&spi3_sleep>;
 pinctrl-names = "default", "sleep";
 cs-gpios = <&gpio0 17 GPIO_ACTIVE_LOW>;
};

Then confirm the generated configuration.

How to check what Kconfig actually selected

After building, inspect:

build/zephyr/.config

Useful searches:

grep CONFIG_SPI build/zephyr/.config
grep CONFIG_SPI_NRFX build/zephyr/.config
grep CONFIG_NRFX_SPIM build/zephyr/.config
grep CONFIG_GPIO build/zephyr/.config
grep CONFIG_PINCTRL build/zephyr/.config

This is safer than guessing.

For example, if your app has:

CONFIG_SPI=y

and your devicetree enables &spi3, the generated .config may show additional selected symbols that you didn’t write manually in prj.conf.

The GPIOTE trap: `CONFIG_NRFX_GPIOTE`

Do not force this manually:

CONFIG_NRFX_GPIOTE=y

This can fail or produce warnings depending on the NCS / Zephyr version, because some nrfx symbols are internal or selected indirectly.

Instead, enable the features that require GPIO / interrupts:

CONFIG_GPIO=y

And describe the interrupt pin in devicetree if the binding supports it:

device3: optical-afe@2 {
 compatible = "manufacturer,device";
 reg = <2>;
 spi-max-frequency = <24000000>;
 int1-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>;
};

Then configure the GPIO interrupt in application code or inside the device driver.

When custom driver work begins

For manual SPI transactions from main.c, this is usually enough:

CONFIG_SPI=y
CONFIG_GPIO=y
CONFIG_PINCTRL=y
CONFIG_LOG=y

When you create a real Zephyr driver for a device, add a driver-specific Kconfig symbol, for example:

CONFIG_DEVICE3=y

That symbol should belong to your custom driver module, not to the generic SPI bus setup.

A clean separation is:

prj.conf:
    CONFIG_SPI=y
    CONFIG_GPIO=y
    CONFIG_PINCTRL=y
    CONFIG_DEVICE3=y

devicetree:
    &spi3 { ... };
    device3: optical-afe@2 {
        compatible = "manufacturer,device"; ... };

driver:
    selected by CONFIG_DEVICE3

Kconfig doesn’t replace devicetree

Kconfig enables software features.

Devicetree describes hardware.

For SPI, both are needed:

Kconfig:
    "Build SPI support into the firmware."

Devicetree:
    "Use SPI3, on these pins, with these chip-selects,
    and these child devices."

So this is incomplete:

CONFIG_SPI=y

Unless the SPI bus is also enabled in devicetree:

&spi3 {
 status = "okay";
};

Communication Protocols |

🧩 Zephyr SPI Notes for Nordic microcontrollers - Part 3

8. Frequency strategy

9. Chip-select rules

Physical pull-up recommendation

Do not manually toggle CS unless you really need to

Common CS mistakes

Mistake 1: Wrong reg index

Mistake 2: GPIO controller disabled

Mistake 3: CS pin also used by another peripheral

10. Multiple SPI buses vs. multiple devices on one bus

One bus, multiple CS lines

Separate SPI buses

11. Interrupt pins aren’t SPI pins

Where interrupt properties belong

The binding must define the property

Application-level interrupt setup

Why defer work?

12. Bindings for custom drivers

Devicetree node after adding the binding

Connecting the driver to Kconfig and CMake

What zephyr/module.yml does

Making the module visible to Zephyr

Option 1: Pass ZEPHYR_EXTRA_MODULES during build

Option 2: Add the module to west.yml

13. Early debugging checklist

Layer 1: build configuration

Common build-time failures

Layer 2: runtime readiness

Identity and status checks

Layer 3: electrical behavior

Runtime failure table

14. Logic analyzer / oscilloscope checks

What a healthy transaction looks like

Basic checks

Check command alignment

Check SPI mode

Check MISO contention

Check power-gated devices

15. An example of a bring-up order for custom boards

Phase 1: Hardware sanity

Phase 2: Devicetree sanity

Phase 3: C-level readiness

Phase 4: First transaction

Phase 5: Add devices one by one

Phase 6: Functional tests

Phase 7: Frequency optimization

Phase 8: Power management testing

Phase 9: Production-driver structure

16. Final checklist before blaming the driver

Devicetree

Kconfig / build

C access pattern

SPI protocol

Chip-select behavior

Hardware and power

Shared bus behavior

Interrupts and auxiliary GPIOs

Measurement

🧩 Zephyr SPI Notes for Nordic microcontrollers - Part 2

5. Access patterns in C

SPI_DT_SPEC_GET()

SPI_DT_SPEC_INST_GET()

DEVICE_DT_GET()

Definition of a hardware binding

SPI Operating modes

Operation Flags

Different operation flags per device

6. __device_dts_ord_*: what the error really means

Why this error happens

Case 1: Generic SPI child accessed as a real device

Why SPI_DT_SPEC_GET() is different

Case 2: The SPI bus or GPIO controllers weren’t fully enabled

Case 3: Forcing the wrong Kconfig symbols

7. Basic SPI transmit / receive helpers

Write-only transaction

Full-duplex transceive

Write command, then read response in one CS window

RAM-backed buffers are the safest bring-up pattern

Device-specific wrappers should build the command

Mistake 1: Wrong `reg` index

What `zephyr/module.yml` does

Option 1: Pass `ZEPHYR_EXTRA_MODULES` during build

Option 2: Add the module to `west.yml`

`SPI_DT_SPEC_GET()`

`SPI_DT_SPEC_INST_GET()`

`DEVICE_DT_GET()`

6. `__device_dts_ord_*`: what the error really means

Why `SPI_DT_SPEC_GET()` is different

2. `nordic,nrf-spim` vs `nordic,nrf-spi`

Meaning of `NRF_PSEL()`

4. `prj.conf` / Kconfig checklist

Minimal `prj.conf` for manual SPI bring-up

The GPIOTE trap: `CONFIG_NRFX_GPIOTE`