I welcome you to this part of my review about Arduino Nano 33 BLE Sense. My review is split into multiple blog posts. You can find all my thoughts about this Arduino and related parts in chapters with name beginning with "Review" like this one. There are also articles describing test projects which I have done for gathering experiences with board and some tutorials. Main page of review contains summary and final score. Following Table of Contents contains links to other parts of my roadtest review.
Table of Contents
- Introduction
- Review of Development Board
- Review of Onboard Sensors
- Review of Microcontroller and BLE Module
- Review of Software
- Review of Documentation (this article)
- Tutorial 01: Accessing Sensor Values
- Tutorial 02: nRF52840 Application without Arduino IDE
Review of Documentation
In this chapter I will describe available documentation and its quality.
Documentation of Arduino (Development Board)
Because board is not so complex it is easy to understand board without any further documentation needed but it is still available. The most useful document is pinout. Pinout is printed only on bottom side of board, so PDF handout is very useful. Pinout can be easily found on store page of this Arduino, but it is also available in PDF with further details about jumpers and test points. Schematic is also available. Schematics is available in eagle format or exported to PDF. PDF variant does not support search and it is exported as bitmap which is common to schematics exported from eagle. I printed it to PDF and my PDF was searchable.
Lastly, the biggest advantage of Arduino is availability of many materials from community online. When you face almost any issue, you are not the first person who face it and you can google for it.
Documentation of MCU
nRF52840 MCU has very brief documentation. Product brief is available online and product specification can be downloaded as PDF. It is detailed but lack many important information. I had to do many guesses when I tried to used peripherals without SDK. For example, description of RXD register of TWI (Two Wire Interface – I2C) is just “RXD register”, but this you probably guessed from name and there are not specified more important things about timing required for reading this register, when value in register change, if some bit is cleared or set by reading this register and so on. Document looks correct and I did not find any mistake when roadtesting. There are good examples and recommendations. Documentation is human readable. There are clearly described all architectural concepts used in MCU. Because MCU has limited clock configuration possible documentation contains many prescallers for generating clocks for buses like UART, I2C, PDM and so on expressed as magic numbers and there is no formula how to calculate value for your own frequency. For example, there are mentioned that if you want baudrate 9600 you should set specified register to 0x00275000. If you want some uncommon value like 10000, you must try determining formula yourself, guess or do experiments.
Document does not contain detailed documentation for peripherals which you probably never use manually like 2.4GHz radio. Also, there are very brief documentation for AMR CryptoCell 310.
Documentation of Sensors
Most information about sensors are presented in datasheet. Datasheets for all sensors are easy to read, contains all important details about sensors and contains described interface how to use sensors. There are some undescribed features and information, but most major functions of sensors are described correctly, and level of details is adequate.
Documentation of Arduino Libraries
Arduino libraries are mainly documented by examples. There are easy to understand simple short examples and very few examples are complicated. Examples are self-documenting and there are few comments in code. There is no explicit documentation (PDF or website) for libraries but is not necessary. Libraries are open source so you can find additional information in their code if you have sufficient knowledge.
Documentation of nRF5 SDK
I personally think that documentation for nRF5 SDK (and other SDKs from Nordic) is insufficient. There is some documentation online but most important part is downloadable locally and it is presented as static HTMLs generated from Doxegen. There are some pages with description and some articles named by “Getting started” but I consider them as totally useless. There are still many concepts totally undescribed. Many useful information about library integration and getting started I found on external websites and personal blogs. There should be one step by test tutorial how to write blinky but there is nothing like this. Online getting started guide mostly describe (also very complicated) process of installation environment and it is mostly outdated (application responsible for installing warns you about that and it navigate you to correct newer approach of installing SDK). Getting started guide ends with “just select some example and run it”. There are no description of examples which to choose, there are no description where to find examples, there are no description how to open it in IDE, there are no description how to debug it when you do not use J-Link, there are no description how to integrate other driver if you want to extend example, and so on. This platform does not support any “quick start”, all starts are very slow. You must learn a lot and spend lot of time by understanding how nRF5 SDK is designed. Many of required information are fragmented on many sources. Some of them are available online and some of them are available as offline docs. In fact, many of things which I mentioned as missing are described in offline documentation which is hard to find when you are new to this platform (In fact, I also do not remember on which page I originally found it).
Nordic supports many IDEs and preferred SES is not used on all places. Some documentation contains screenshots of Keil and of course there are no description how to do this step using preferred IDE SES. Lastly, there are complication with naming of SDKs. There are two SDKs: “nRF5 SDK” and “nRF connect SDK”. You probably will be confused by this, and you probably will spend some time in documentation for incorrect SDK like I did.
Documentation of Soft Devices
SoftDevices are described in the same offline documentation as most of nRF5 SDK. They are described little bit better than other parts of SDK. I think it is because soft devices are totally closed source and documentation is only point where you can find any relevant information. There are no online materials, even tutorials how to use soft devices. There are examples in SDK folder similarly to peripheral driver examples. Soft Devices and interfaces to SDK are of course not integrated in template project and you must do that manually. As expected, there are no documentation for doing that. I recommend copy some BLE example if you want to develop this kind of project.
