Vendor hooks

Vendor hooks are a software mechanism that allows adding custom Spinel commands. Such vendor-specific commands can be used to add support for enhanced application features. For example, they allow you to add radio or crypto functionalities, whose settings are managed from the host device.

In nRF Connect SDK, your implementation of the vendor hooks file is compiled by OpenThread within the NCP component. The only information needed for compilation is the file location. In this way, you can implement new features in the application or elsewhere without having to modify OpenThread components.

Vendor hooks are strictly connected to the Spinel protocol used in serial communication between host device and the MCU board working in Thread NCP or RCP architecture. Spinel uses serial frames with commands that describe the activity to perform (for example, get or set), and with properties that define the object on which the activity is to be performed. You can use the available commands and properties, but also define your set of instructions to provide new features by using the vendor hooks.


Both devices used for communication must support user-defined commands and properties to achieve the expected result. See the following sections for information about how to add your features on the host and the NCP/RCP devices.

ID range of general vendor properties

The Spinel protocol associates specific properties with numeric identifiers. The ID range reserved for the vendor properties spans from 0x3c00 to 0x4000.

You are not allowed to use IDs from outside this range for your properties, as this might negatively affect the Spinel protocol operation, and the vendor hooks mechanism will not work.

Host device configuration

In most cases, the host device uses tools that support the Spinel protocol (like wpantund or Pyspinel) to communicate with the NCP/RCP device. You can, however, use another tool as long as it supports the Spinel protocol.

Adding properties in Pyspinel

Pyspinel is the recommended tool for adding properties, given its ease-of-use.

To configure new properties in Pyspinel, you must update the following files:

  • - This file contains the VENDOR_SPINEL class, which stores definitions of the identifier values of vendor properties. Use this file to add properties.

  • - This file contains definitions of handler methods called on property detection. Use this file to add definitions of handlers for your properties.

  • - This file contains methods to capture property occurrences from the console and call proper handlers.

These files are located in the vendor directory, which can be found in the main project directory.

Complete the following steps to add a property in Pyspinel:

  1. Clone the Pyspinel respository and install the tool.

  2. Navigate to the vendor directory that contains the,, and files. This directory is located in the main project directory.

  3. Open the file for editing.

  4. Add properties to the file. For example, add the following properties:

    • PROP_VENDOR_NAME, which is used to get the vendor name from the device.

    • PROP_VENDOR_AUTO_ACK_ENABLED, which is used to get or set the auto ACK mode state.

    The class should contain code similar to the following:

    class VENDOR_SPINEL(object):
      Class to extend SPINEL constant variables for example:
          PROP_VENDOR__BEGIN = 0x3C00
          PROP_VENDOR__END = 0x4000
      PROP_VENDOR__BEGIN = 0x3C00
      PROP_VENDOR__END = 0x4000

    You can also add your own properties, but you must assign them IDs from the proper vendor range.

  5. Open the file for editing.

  6. In the file, add definitions of handlers. For example, for the properties added in the file:

    class VendorSpinelPropertyHandler(SpinelCodec):
      Class to extend Spinel property Handler with new methods.
      Methods define parsers for Vendor Hooks for example:
      `def VENDOR_HOOK_PROPERTY(self, _wpan_api, payload): return self.parse_C(payload)`
      def NAME(self, _, payload):
          return self.parse_U(payload)
      def AUTO_ACK(self, _, payload):
          return self.parse_C(payload)
    WPAN_PROP_HANDLER = VendorSpinelPropertyHandler()
    # Parameter to extend SPINEL_PREP_DISPATCH with Vendor properties for example:


    Handlers call different parsing methods depending on the type of data passed with the property. In this case, NAME is of string type and AUTO_ACK is of uint8 type, so methods parse_U and parse_C should be used. For details, see the SpinelCodec class in spinel/

  7. Open the file for editing.

  8. Extend the list of command names with the new properties and make sure they are included in the do_vendor method:

    class VendorSpinelCliCmd():
      Extended Vendor Spinel Cli with vendor hooks commands.
          spinel-cli > vendor help
          Available vendor commands:
      vendor_command_names = ['help', 'name', 'auto_ack']
      def do_vendor(self, line):
          params = line.split(" ")
          if params[0] == 'help':
              self.print_topics("\nAvailable vendor commands:",
                                VendorSpinelCliCmd.vendor_command_names, 15, 30)
          elif params[0] == 'name':
              self.handle_property(None, VENDOR_SPINEL.PROP_VENDOR_NAME)
          elif params[0] == 'auto_ack':
              if len(params) > 1:
                  self.handle_property(params[1], VENDOR_SPINEL.PROP_VENDOR_AUTO_ACK_ENABLED)
                  self.handle_property(None, VENDOR_SPINEL.PROP_VENDOR_AUTO_ACK_ENABLED)

NCP/RCP device configuration

In nRF Connect SDK, the OpenThread NCP base component is responsible for processing Spinel frames and performing appropriate operations. If it finds a frame with an unknown property ID, but one that fits the vendor ID range, it calls vendor handler methods. You must define these methods beforehand.

Handler methods can check the property ID and perform different actions depending on its value. They can also ignore the value, for example, if the property was defined by another vendor and you want to filter it out.

For a detailed description of how to enable the vendor hook feature in a sample, see the Thread: Co-processor sample documentation.

Testing vendor hooks after configuration

To test the vendor hook feature, you need a development kit that is programmed with either the Thread: Co-processor sample or another compatible sample.

Complete the following steps:

  1. Connect the development kit’s SEGGER J-Link USB port to the USB port on your PC with an USB cable.

  2. Get the development kit’s serial port name (for example, /dev/ttyACM0).

  3. Open a shell and run Pyspinel by using the following command, with baud_rate set to 1000000 and serial_port_name set to the port name from the previous step:

    python3 -u serial_port_name -b baud_rate
  4. In the Pyspinel shell, run the following command to check the list of available vendor properties:

    spinel-cli > vendor help

    The output looks similar to the following:

    Available vendor commands:
    help  name  auto_ack
  5. In the Pyspinel shell, run the following command to get the device vendor name:

    spinel-cli > vendor name

    The output looks similar to the following:

    Nordic Semiconductor
  6. In the Pyspinel shell, run the auto_ack command to get the current state of the device auto ACK mode:

    spinel-cli > vendor auto_ack

    The output looks similar to the following:

  7. In the Pyspinel shell, run the auto_ack command with a value to change the current state of the device auto ACK mode:

    spinel-cli > vendor auto_ack 0

    The output looks similar to the following: