Application Note
nRF Connect: Developing a custom firmware for nRF5 based Würth Elektronik eiSos Radio Modules
Abbreviations
1 Introduction
This application note gives a short overview about the options to create a custom firmware for Würth Elektronik eiSos radio modules by using the hardware platform and the embedded nRF5 system on chip. It presents options on firmware development environments and accessories (like SDKs) for the use within the nRF5 ecosystem.
Supported Würth Elektronik eiSos radio modules:
Table 1: Integrated radio chips
The radio modules of the Proteus series contain a firmware, which allows to control the radio module via commands, that are send by a connected micro processor via UART/SPI. In addition, they provide the so called ¨SPP-like¨ profile on the Bluetooth® LE interface for data exchange with other Bluetooth® LE enabled devices. The Ophelia-I contains no firmware and comes with an empty flash memory.
In both cases, either using Ophelia-I or a Proteus radio module, it may be necessary to develop an own firmware tailored to the applications needs.
For firmware development on base of Nordic semiconductor Bluetooth® LE chips, Nordic semiconductor provides two options:
- The nRFConnect SDK [3] that uses the Zephyr [8] RTOS with the integrated Bluetooth® LE stack (SoftDevice Controller subsystem). There are regular releases (usually 4 major releases per year) of new versions of the nRF Connect SDK as its development and advancement is in the focus of Nordic Semiconductor and various other contributors.
- The nRF5 SDK [4] that uses the so called ¨Soft devices¨ that integrate the Bluetooth® LE stack and the RTOS. There are various soft devices available, each providing a different function set and compatibility to different radio chips.
Table 2: Example: SoftDevice compatibility
The development of the nRF5 SDK was taken out of focus with major version 17. That means: Only bug fixes and maintenance releases are still done. This path will therefore not support Bluetooth® versions newer than 5.1.
As the nRF5 SDK won’t be adapted to new Bluetooth® standards, Bluetooth® LE features or new Bluetooth® LE chip sets, we focus on the nRF Connect SDK in the remaining part of the document.
2 Using nRF Connect SDK for firmware development
As motivated above, in this chapter we consider the set-up of the development environment on base of the nRF Connect SDK.
The nRF Connect SDK uses CMake [1] and the resulting make files to compile the provided Bluetooth® stack (Zephyr RTOS) and the application source code. The IDE with best support and comfort is VS Code [6] equipped with the nRF Connect plug-in that provides all the features needed to develop a firmware on base of the Nordic Semiconductor radio chips.
To install and set-up nRF Connect using VS Code, Nordic Semiconductor provides a play list on YouTube describing the work flow.
It’s recommended to have administrator access and an internet connection on the PC where you install VS Code, nRF Connect and their respective dependencies, drivers and tools.
nRF Connect for VS Code tutorials:
https://www.youtube.com/playlist?list=PLx_tBuQ_KSqEt7NK-H7Lu78lT2OijwIMl
1. Installation
Use the nRF Connect tool to download all required sources, like Zephyr, from GitHub.
2. Create an application
Copy one of the various sample applications as a starting point for an own firmware development.
3. Building an application & Exploring windows
Bind your application to the hardware (for example Proteus-III evaluation board) and build the firmware. See also chapter 2.1 and 2.2 for details on selecting the Würth Elektronik eiSos radio module hardware platform.
4. Flash an application to board
Flash and run the firmware on the hardware. See also chapter 2.3 to connect the Würth Elektronik eiSos hardware to the PC.
5. Debugging
Debug the firmware on the hardware. See also chapter 2.3 to connect the Würth Elektronik eiSos hardware to the PC.
6. Migrating from other IDEs to Microsoft VisualStudio Code (¨VS Code¨)
Less interesting for new developments: Firmware migration from previous supported IDEs to VS Code.
7. Tips &Tricks
Best practices when using nRF Connect SDK in VS Code.
2.1 Choosing a Würth Elektronik eiSos board file
In the step 3 ¨Building an application & Exploring windows¨ the underlying hardware is selected. By default, the nRF Connect SDK provides a bunch of supported boards. Würth Elektronik eiSos periodically adds the description of the available evaluation boards, like Proteus-III evaluation board, to the Zephyr RTOS. In case of a new nRF Connect SDK release version, these boards are automatically available in the drop down menu (see figure 1) of the board selection step.
Figure 1: Select a Würth Elektronik eiSos board
In case the current version of the nRF Connect SDK does not include the description of the Würth Elektronik eiSos boards, please download it from
http://www.we-online.de/nrf-connect-board
and save it in the board file directory of the Zephyr RTOS (see figure 2). After a restart of the VS Code, the boards are available in the drop down menu, and ready for selection.
Figure 2: Board file directory
These board files basically contain the radio module related pin-out information, such as UART pins, LEDs and buttons, as well as the use of the internal RC low frequency crystal, in case the radio module does not provide the external low frequency crystal on its PCB.
As several radio modules and the corresponding evaluation boards share the same hardware, the board name like ¨we_ophelia1ev_nrf52805¨ represents the hardware of several Würth Elektronik eiSos products. To choose the right board file for the purchased hardware, please refer to table 3:
Table 3: Choose the right board
2.2 Choosing a board with small memory
The Ophelia-I and Proteus-e use the Nordic Semiconductor chip nRF52805 [2] which provides only 192 KB flash and 24 KB RAM. In case the full feature set of the Zephyr Bluetooth® stack shall be used within this radio chip, the flash and RAM memory limitations are exceeded. Thus it is necessary to use the minimal build configuration ¨prj_minimal.conf¨ (see figure 3) as a starter and add more features later depending on the need of the application and available memory resources.
Figure 3: Choose minimal configuration
2.3 Connecting the Würth Elektronik eiSos hardware to the PC
To flash and debug the firmware on the radio module, the corresponding evaluation board must be connected to the PC.
First of all, a USB-cable must be connected to the USB-plug on the evaluation board to power-source it. Next, the debug probe must be attached to the evaluation boards 2x10 pin debug connector. The considered radio chips provide a SWD (serial wire debug) interface that can be accessed to flash and debug the firmware. On modules with firmware (Proteus) you will need to perform the action "unprotect" before you will be able to access the module for your development. This action will perform a mass erase on the memory of the module and enable the access to SWD.
We recommend to use a SEGGER J-Link debug probe [5], like the J-Link Plus or Ultra+.
Figure 4: Example: Evaluation board Proteus-II
For more detailed information about the evaluation boards, please refer to the corresponding evaluation board manual.
3 Certification of a Bluetooth custom firmware
As all Bluetooth® LE radio modules sold by Würth Elektronik eiSos have been tested to comply to various national regulations, parts of the test results and certifications can be reused for the new custom radio module.
This is only possible for custom products using the Bluetooth® LE radio function.
- The European CE is a self declaration. To gain this, a so called "Declaration of Identity" referring to the radio test reports1 of the original product (radio module including the original firmware) is sufficient.
- For the American FCC and Canadian IC a so called "Change in ID" process must be done. In this process the test results1 related to the FCC/ISED ID of the original product are copied to a new FCC/ISED ID that is created for the new custom product.
- TELEC certification for Japan does not allow any sort inheritance from an already existing certification when a custom firmware is in use. This means a full certification for the custom product must be performed.
- As the custom firmware has not been developed by Würth Elektronik eiSos, the module integrator can not use the "end device" Bluetooth® listing of the original product. To gain the Bluetooth® listing for the new custom product, please refer to the application note "Bluetooth® listing guide" [7]. This application note guides you step by step through the listing process, in case a custom firmware shall be listed with the Bluetooth® SIG. It involves becoming Bluetooth® member and buying the required QDID from the Bluetooth® SIG.
---------------------------------------------------
1Test reports are provided on request.
4 References
[1] CMake. https://cmake.org/overview/
[2] Nordic Semiconductor. Nordic nRF52805 resources. https://www.nordicsemi.com/ products/nrf52805
[3] Nordic Semiconductor. nRF Connect SDK. https://www.nordicsemi.com/Products/ Development-software/nRF-Connect-SDK
[4] Nordic Semiconductor. nRF5 SDK. https://www.nordicsemi.com/Products/ Development-software/nrf5-sdk
[5] SEGGER J-Link debug probes. https://www.segger.com/products/debug-probes/ j-link/
[6] Visual Studio Code. https://code.visualstudio.com/
[7] Würth Elektronik. Application note 27 - Bluetooth listing guide. https://www.we-online. com/ANR027
[8] Zephyr RTOS on GitHub. https://github.com/zephyrproject-rtos/zephyr
5 Important notes
The following conditions apply to all goods within the wireless connectivity product range of Würth Elektronik eiSos GmbH & Co. KG:
5.1 General customer responsibility
Some goods within the product range of Würth Elektronik eiSos GmbH & Co. KG contain statements regarding general suitability for certain application areas. These statements about suitability are based on our knowledge and experience of typical requirements concerning the areas, serve as general guidance and cannot be estimated as binding statements about the suitability for a customer application. The responsibility for the applicability and use in a particular customer design is always solely within the authority of the customer. Due to this fact, it is up to the customer to evaluate, where appropriate to investigate and to decide whether the device with the specific product characteristics described in the product specification is valid and suitable for the respective customer application or not. Accordingly, the customer is cautioned to verify that the documentation is current before placing orders.
5.2 Customer responsibility related to specific, in particular safety-relevant applications
It has to be clearly pointed out that the possibility of a malfunction of electronic components or failure before the end of the usual lifetime cannot be completely eliminated in the current state of the art, even if the products are operated within the range of the specifications. The same statement is valid for all software sourcecode and firmware parts contained in or used with or for products in the wireless connectivity and sensor product range of Würth Elektronik eiSos GmbH & Co. KG. In certain customer applications requiring a high level of safety and especially in customer applications in which the malfunction or failure of an electronic component could endanger human life or health, it must be ensured by most advanced technological aid of suitable design of the customer application that no injury or damage is caused to third parties in the event of malfunction or failure of an electronic component.
5.3 Best care and attention
Any product-specific data sheets, manuals, application notes, PCN’s, warnings and cautions must be strictly observed in the most recent versions and matching to the products firmware revisions. This documents can be downloaded from the product specific sections on the wireless connectivity homepage.
5.4 Customer support for product specifications
Some products within the product range may contain substances, which are subject to restrictions in certain jurisdictions in order to serve specific technical requirements. Necessary information is available on request. In this case, the field sales engineer or the internal sales person in charge should be contacted who will be happy to support in this matter.
5.5 Product improvements
Due to constant product improvement, product specifications may change from time to time. As a standard reporting procedure of the Product Change Notification (PCN) according to the JEDEC-Standard, we inform about major changes. In case of further queries regarding the PCN, the field sales engineer, the internal sales person or the technical support team in charge should be contacted. The basic responsibility of the customer as per section 5.1 and 5.2 remains unaffected. All wireless connectivity module driver software ¨wireless connectivity SDK¨ and it’s source codes as well as all PC software tools are not subject to the Product Change Notification information process.
5.6 Product life cycle
Due to technical progress and economical evaluation we also reserve the right to discontinue production and delivery of products. As a standard reporting procedure of the Product Termination Notification (PTN) according to the JEDEC-Standard we will inform at an early stage about inevitable product discontinuance. According to this, we cannot ensure that all products within our product range will always be available. Therefore, it needs to be verified with the field sales engineer or the internal sales person in charge about the current product availability expectancy before or when the product for application design-in disposal is considered. The approach named above does not apply in the case of individual agreements deviating from the foregoing for customer-specific products.
5.7 Property rights
All the rights for contractual products produced by Würth Elektronik eiSos GmbH & Co. KG on the basis of ideas, development contracts as well as models or templates that are subject to copyright, patent or commercial protection supplied to the customer will remain with Würth Elektronik eiSos GmbH & Co. KG. Würth Elektronik eiSos GmbH & Co. KG does not warrant or represent that any license, either expressed or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right relating to any combination, application, or process in which Würth Elektronik eiSos GmbH & Co. KG components or services are used.
5.8 General terms and conditions
Unless otherwise agreed in individual contracts, all orders are subject to the current version of the "General Terms and Conditions of Würth Elektronik eiSos Group", last version available at www.we-online.com.
6 Legal notice
6.1 Exclusion of liability
Würth Elektronik eiSos GmbH & Co. KG considers the information in this document to be correct at the time of publication. However, Würth Elektronik eiSos GmbH & Co. KG reserves the right to modify the information such as technical specifications or functions of its products or discontinue the production of these products or the support of one of these products without any written announcement or notification to customers. The customer must make sure that the information used corresponds to the latest published information. Würth Elektronik eiSos GmbH & Co. KG does not assume any liability for the use of its products. Würth Elektronik eiSos GmbH & Co. KG does not grant licenses for its patent rights or for any other of its intellectual property rights or third-party rights. Notwithstanding anything above, Würth Elektronik eiSos GmbH & Co. KG makes no representations and/or warranties of any kind for the provided information related to their accuracy, correctness, completeness, usage of the products and/or usability for customer applications. Information published by Würth Elektronik eiSos GmbH & Co. KG regarding third-party products or services does not constitute a license to use such products or services or a warranty or endorsement thereof.
6.2 Suitability in customer applications
The customer bears the responsibility for compliance of systems or units, in which Würth Elektronik eiSos GmbH & Co. KG products are integrated, with applicable legal regulations. Customer acknowledges and agrees that it is solely responsible for compliance with all legal, regulatory and safety-related requirements concerning its products, and any use of Würth Elektronik eiSos GmbH & Co. KG components in its applications, notwithstanding any applications-related in-formation or support that may be provided by Würth Elektronik eiSos GmbH & Co. KG. Customer represents and agrees that it has all the necessary expertise to create and implement safeguards which anticipate dangerous consequences of failures, monitor failures and their consequences lessen the likelihood of failures that might cause harm and take appropriate remedial actions. The customer will fully indemnify Würth Elektronik eiSos GmbH & Co. KG and its representatives against any damages arising out of the use of any Würth Elektronik eiSos GmbH & Co. KG components in safety-critical applications.
6.3 Trademarks
AMBER wireless is a registered trademark of Würth Elektronik eiSos GmbH & Co. KG. All other trademarks, registered trademarks, and product names are the exclusive property of the respective owners.
6.4 Usage restriction
Würth Elektronik eiSos GmbH & Co. KG products have been designed and developed for usage in general electronic equipment only. This product is not authorized for use in equipment where a higher safety standard and reliability standard is especially required or where a failure of the product is reasonably expected to cause severe personal injury or death, unless the parties have executed an agreement specifically governing such use. Moreover, Würth Elektronik eiSos GmbH & Co. KG products are neither designed nor intended for use in areas such as military, aerospace, aviation, nuclear control, submarine, transportation (automotive control, train control, ship control), transportation signal, disaster prevention, medical, public information network etc. Würth Elektronik eiSos GmbH & Co. KG must be informed about the intent of such usage before the design-in stage. In addition, sufficient reliability evaluation checks for safety must be performed on every electronic component, which is used in electrical circuits that require high safety and reliability function or performance. By using Würth Elektronik eiSos GmbH & Co. KG products, the customer agrees to these terms and conditions.
7 License terms
This License Terms will take effect upon the purchase and usage of the Würth Elektronik eiSos GmbH & Co. KG wireless connectivity products. You hereby agree that this license terms is applicable to the product and the incorporated software, firmware and source codes (collectively, "Software") made available by Würth Elektronik eiSos in any form, including but not limited to binary, executable or source code form. The software included in any Würth Elektronik eiSos wireless connectivity product is purchased to you on the condition that you accept the terms and conditions of this license terms. You agree to comply with all provisions under this license terms.
7.1 Limited license
Würth Elektronik eiSos hereby grants you a limited, non-exclusive, non-transferable and royalty-free license to use the software and under the conditions that will be set forth in this license terms. You are free to use the provided Software only in connection with one of the products from Würth Elektronik eiSos to the extent described in this license terms. You are entitled to change or alter the source code for the sole purpose of creating an application embedding the Würth Elektronik eiSos wireless connectivity product. The transfer of the source code to third parties is allowed to the sole extent that the source code is used by such third parties in connection with our product or another hardware provided by Würth Elektronik eiSos under strict adherence of this license terms. Würth Elektronik eiSos will not assume any liability for the usage of the incorporated software and the source code. You are not entitled to transfer the source code in any form to third parties without prior written consent of Würth Elektronik eiSos. You are not allowed to reproduce, translate, reverse engineer, decompile, disassemble or create derivative works of the incorporated Software and the source code in whole or in part. No more extensive rights to use and exploit the products are granted to you.
7.2 Usage and obligations
The responsibility for the applicability and use of the Würth Elektronik eiSos wireless connectivity product with the incorporated Firmware in a particular customer design is always solely within the authority of the customer. Due to this fact, it is up to you to evaluate and investigate, where appropriate, and to decide whether the device with the specific product characteristics described in the product specification is valid and suitable for your respective application or not. You are responsible for using the Würth Elektronik eiSos wireless connectivity product with the incorporated Firmware in compliance with all applicable product liability and product safety laws. You acknowledge to minimize the risk of loss and harm to individuals and bear the risk for failure leading to personal injury or death due to your usage of the product. Würth Elektronik eiSos’ products with the incorporated Firmware are not authorized for use in safety-critical applications, or where a failure of the product is reasonably expected to cause severe personal injury or death. Moreover, Würth Elektronik eiSos’ products with the incorporated Firmware are neither designed nor intended for use in areas such as military, aerospace, aviation, nuclear control, submarine, transportation (automotive control, train control, ship control), transportation signal, disaster prevention, medical, public information network etc. You shall inform Würth Elektronik eiSos about the intent of such usage before design-in stage. In certain customer applications requiring a very high level of safety and in which the malfunction or failure of an electronic component could endanger human life or health, you must ensure to have all necessary expertise in the safety and regulatory ramifications of your applications. You acknowledge and agree that you are solely responsible for all legal, regulatory and safety-related requirements concerning your products and any use of Würth Elektronik eiSos’ products with the incorporated Firmware in such safety-critical applications, notwithstanding any applications-related information or support that may be provided by Würth Elektronik eiSos. YOU SHALL INDEMNIFY WÜRTH ELEKTRONIK EISOS AGAINST ANY DAMAGES ARISING OUT OF THE USE OF WÜRTH ELEKTRONIK EISOS’ PRODUCTS WITH THE INCORPORATED FIRMWARE IN SUCH SAFETY-CRITICAL APPLICATIONS.
7.3 Ownership
The incorporated Firmware created by Würth Elektronik eiSos is and will remain the exclusive property of Würth Elektronik eiSos.
7.4 Firmware update(s)
You have the opportunity to request the current and actual Firmware for a bought wireless connectivity Product within the time of warranty. However, Würth Elektronik eiSos has no obligation to update a modules firmware in their production facilities, but can offer this as a service on request. The upload of firmware updates falls within your responsibility, e.g. via ACC or another software for firmware updates. Firmware updates will not be communicated automatically. It is within your responsibility to check the current version of a firmware in the latest version of the product manual on our website. The revision table in the product manual provides all necessary information about firmware updates. There is no right to be provided with binary files, so called "Firmware images", those could be flashed through JTAG, SWD, Spi-Bi-Wire, SPI or similar interfaces.
7.5 Disclaimer of warranty
THE FIRMWARE IS PROVIDED "AS IS". YOU ACKNOWLEDGE THAT WÜRTH ELEKTRONIK EISOS MAKES NO REPRESENTATIONS AND WARRANTIES OF ANY KIND RELATED TO, BUT NOT LIMITED TO THE NON-INFRINGEMENT OF THIRD PARTIES’ INTELLECTUAL PROPERTY RIGHTS OR THE MERCHANTABILITY OR FITNESS FOR YOUR INTENDED PURPOSE OR USAGE. WÜRTH ELEKTRONIK EISOS DOES NOT WARRANT OR REPRESENT THAT ANY LICENSE, EITHER EXPRESS OR IMPLIED, IS GRANTED UNDER ANY PATENT RIGHT, COPYRIGHT, MASK WORK RIGHT, OR OTHER INTELLECTUAL PROPERTY RIGHT RELATING TO ANY COMBINATION MACHINE, OR PROCESS IN WHICH THE WÜRTH ELEKTRONIK EISOS’ PRODUCT WITH THE INCORPORATED FIRMWARE IS USED. INFORMATION PUBLISHED BY WÜRTH ELEKTRONIK EISOS REGARDING THIRD-PARTY PRODUCTS OR SERVICES DOES NOT CONSTITUTE A LICENSE FROM WÜRTH ELEKTRONIK EISOS TO USE SUCH PRODUCTS OR SERVICES OR A WARRANTY OR ENDORSEMENT THEREOF.
7.6 Limitation of liability
Any liability not expressly provided by Würth Elektronik eiSos shall be disclaimed. You agree to hold us harmless from any third-party claims related to your usage of the Würth Elektronik eiSos’ products with the incorporated Firmware, software and source code. Würth Elektronik eiSos disclaims any liability for any alteration, development created by you or your customers as well as for any combination with other products.
7.7 Applicable law and jurisdiction
Applicable law to this license terms shall be the laws of the Federal Republic of Germany. Any dispute, claim or controversy arising out of or relating to this license terms shall be resolved and finally settled by the court competent for the location of Würth Elektronik eiSos’ registered office.
7.8 Severability clause
If a provision of this license terms is or becomes invalid, unenforceable or null and void, this shall not affect the remaining provisions of the terms. The parties shall replace any such provisions with new valid provisions that most closely approximate the purpose of the terms.
7.9 Miscellaneous
Würth Elektronik eiSos reserves the right at any time to change this terms at its own discretion. It is your responsibility to check at Würth Elektronik eiSos homepage for any updates. Your continued usage of the products will be deemed as the acceptance of the change. We recommend you to be updated about the status of new firmware and software, which is available on our website or in our data sheet and manual, and to implement new software in your device where appropriate. By ordering a wireless connectivity product, you accept this license terms in all terms.
DIRECT LINK
USEFUL LINKS:
Application Notes : https://we-online.com/en/support/knowledge/application-notes
Services: https://we-online.com/en/products/components/service
Contact : https://we-online.com/en/support/contact
CONTACT INFORMATION
Würth Elektronik eiSos GmbH & Co. KG
Max-Eyth-Str. 1, 74638 Waldenburg, Germany
Tel.: +49 (0) 7942 / 945 – 0
Email: appnotes@we-online.de