PSoC 6 Pioneer Kit Roadtest - Review of Documentation

22 Dec 2020

This post is part of my Roadtest Review of Cypress PSoC 62S2 Wi-Fi & BT5.0 Pioneer Dev Kit - Review. My review is splitted into multiple reviews and tutorials. Main page of review contains brief description of every chapter. Some projects are implemented in multiple variants. Main page of review contains brief description about every chapter, project and variants and contains some reccomendations for reading.

Intruction, Table of Contents, Overview of Table of Contets
Review of Development Board
Review of Microcontroller
Review of Wi-FI and BT Module
Review of Onboard Peripherals
Review of Onboard Programmer and Debugger
Review of Development Software
Review of Documentation (this article)
Project 1 - Serial Interfaces

Project 2 - Simple Cloud Application
- Project done using AWS Service
- Project done using Azure services

Review of Documentation

This chapter of review brings overview of documentation that is related to any resource. I describe the documentation for board itself, for the microcontroller, for Wi-Fi module and some other resources available online.

Documentation of development board

The first documentation you can met are links on the box and printed quick start which inside the box. Quickstart guide describes preinstalled demo and shows pinouts. It is useful when beginning but because pinout itself is very simple to remember (it is described more in chapter “Review of development board”) and some other mappings are written directly on board you probably will not use it regularly. It is good and I have no issue with that. The links printed on board redirects to main page of development board, community forum, store page, technical support page, related product pages and page designed for universities.

The main page of development board https://www.cypress.com/documentation/development-kitsboards/psoc-62s2-wi-fi-bt-pioneer-kit-cy8ckit-062s2-43012 is simple and contains everything interesting about the board. At the end of the page there are 7 files to download. These 7 files are all files related to board only and are available at this single page. This is good because as I mention later board is the only part with all documentation available at one page. Other parts (like MCU) have documentation stored (from the user perspective) randomly at multiple pages. There are two schematics exported in PDF, ZIP folder with HW files like full PCB drawings and BOM and finally there are 3 PDFs. There are two schematics, one for board and second one for module. Schematics and HW files are good and contains lot of interesting information. One of the PDFs is the Quick Start Guide, which is also printed in box, second PDF is Release Notes. The most interesting part of Release Notes is “Limitations and Known Issues”. Currently there is one known issue with board. It is back powering when you have attached USB cable to user USB port of MCU and you have disconnected jumper used to measure power consumption. It is not a significant issue and they mentioned in the document that they will resolve issue in future revision of board. The last PDF is Kit Guide and it contains detailed text description of board, peripherals, connectors, detailed pinouts, jumpers meaning, brief overview of MCU architecture, picture based tutorial how to deploy Hello World example to the board from ModusToolbox and lastly it contains extraction from schematics with text description.

So finally, The development board documentation is good and I have no issue about it.

Documentation of MCU

The documentation for MCU is worse. The main page of MCU https://www.cypress.com/part/cy8c624abzi-s2d44 contains datasheet at the top. There are some details about the MCU. Prices are missing. You need to contact Cypress Sales If you want to know prices. Finally, there application some notes at the bottom of page. The biggest disadvantage is that you cannot find there all documents relevant to that chip. There is no linked technical reference manual (TRM), programming manual, models and symbols for PCB design software and other documents. They are not available here and you must search them yourself.

There is tool for searching documentation. It looks as follows.

If you check Resource Type – TRM and then search for “psoc 6” you will get all documents because tool “forgets” that you had selected TRMs filter. If you do that in opposite order (search first, then filter) It will works as expect. If you search for “psoc 6” it will search TRMs for not only 6^th family of PSoC. The second issue I had with this tool is not caused by tool itself, but it is caused by nonuniform naming conventions in Cypress. For example, if you search for registry TRM (Cypress has separated TRM to two “books” – Architecture and Registers, I will write about that later) for 62 serie of PSoC you find the following

Luckily the first document states that it is Register TRM for PSoC 62 family. But it is not. When you download it and opens that, You will see following document.

As you can see while this TRM is named that target PSoC 62 in fact it targets only subset of that family (models ending with 6 a 7 in main part of name). Onboard MCU is CY8C624A so this document is not the correct one. If you scroll back to picture with search results you can see that the 3^rd entry in search is another registers TRM and this matches only models with 8 and A in name. This is correct document, and it has correctly specified his limitation to subfamily in name while the document for other subfamily does not.

I spent a lot of time searching documents using this tool and I think it is very unintuitive. The next problem is that Cypress probably do all documents fully manually and multiple peoples makes them differently. In fact, If they just links correct documents at the main page of every MCU as they have done with application notes this problem disappears naturally.

Later I found that at the main page of whole PSoC6 family contains Documentation tab which contains links to all documents with distinguished variants and consistent naming.

I still like the way how ST Microelectronics does – all document for any of thousands of MCU variant that they produce has all documents linked at page for every single chip.

Sadly, as part of review I also looked for other PSoC families but there are the same problems. PSoC 5LP family is probably designed and documented by different team so Documentation tab of the same page looks completely different.

Similarly, I tried PSoC 4. To make searching documentation funny they did not provided any Documentation tab at all.

Lower number families of PSoC like PSoC 1, (PSoC 2 does not exists, but PSoC 1 chips are numbered with 2 in name for some unknown reason) and PSoC 3 are not ARM based so I did not researched them so deep.

To summarize it, I am not satisfied with searching for MCU documentation and they have plenty of ways how to improve that.

Documents itself are very good quality. I will describe each important MCU related document.

Datasheet

Datasheet is common for subfamily. They do not make datasheet for every part like ST does. Datasheet for the roadtested MCU is common for 10 parts but it is not problem and datasheet very rarely distinguish between final variations. Differences between models covered by datasheet are described in Order Information section. As you can see on the following picture, documents from Cypress usually contains machine readable table of contents so PDF viewer will display navigation in document for you. Datasheet contains important information to choose the right part. It does not contain detailed description of everything. I like the datasheet. It is exactly what I imagine as good datasheet.

TRM

Technical Reference Manual is split to the two documents – Architecture and Registers. Architecture contains text description of almost all possibilities of every single peripheral included in MCU. But this document describes registers only briefly. Reason for that probably is that most users do not need know anything about registered because they are using some library. And it makes sense. Everything you can read in Architecture TRM, you can do using PDL and do not need know anything about registers. The documentation look like that is written by humans for humans. While TRM’s is very exhausting, it contains lot of things presented in simpler variant to understand than usual. Small issue for me is navigation in document. They have peripherals assigned to sections and if you are using table of contents browser provided by your PDF viewer, you must guess section that your searched peripheral belongs to. Then you must manually expand it. I like flatten design with all peripherals in main level rather than tree.

When I began roadtesting, There were Architecture TRM of revision E and it’s navigation was quite good (expect nesting noted before). But later Cypress release revision F. Revision F had broken navigation. I asked at Cypress community forum about that https://community.cypress.com/thread/64161 and they told me that they will forward issue to their internal team to resolve issue. Issue was not resolved before readtest deadline. So I cant write here, that they have resolved it. I am still using revision E.

Sometimes I felt that TRMs (Registry and Architecture) are incomplete. TRM should be as most detailed as possible and describe everything without any exception. When developing some applications, I found that library (PDL) mention some registers which are not covered in TRMs. For example, it is CFG_SIO register of GPIO module. If you check PDL definition of registers, you can see that it exists and it is at offset 0x50 from base address of port configuration.

typedef struct {
  __IOM uint32_t OUT; /*!< 0x00000000 Port output data register */
  __IOM uint32_t OUT_CLR; /*!< 0x00000004 Port output data clear register */
  __IOM uint32_t OUT_SET; /*!< 0x00000008 Port output data set register */
  __IOM uint32_t OUT_INV; /*!< 0x0000000C Port output data invert register */
   __IM uint32_t IN; /*!< 0x00000010 Port input state register */
  __IOM uint32_t INTR;                          /*!< 0x00000014 Port interrupt status register */
  __IOM uint32_t INTR_MASK; /*!< 0x00000018 Port interrupt mask register */
   __IM uint32_t INTR_MASKED; /*!< 0x0000001C Port interrupt masked status register */
  __IOM uint32_t INTR_SET; /*!< 0x00000020 Port interrupt set register */
   __IM uint32_t RESERVED[7];
  __IOM uint32_t INTR_CFG; /*!< 0x00000040 Port interrupt configuration register */
  __IOM uint32_t CFG;                           /*!< 0x00000044 Port configuration register */
  __IOM uint32_t CFG_IN; /*!< 0x00000048 Port input buffer configuration register */
  __IOM uint32_t CFG_OUT; /*!< 0x0000004C Port output buffer configuration register */
  __IOM uint32_t CFG_SIO; /*!< 0x00000050 Port SIO configuration register */
   __IM uint32_t RESERVED1;
  __IOM uint32_t CFG_IN_AUTOLVL; /*!< 0x00000058 Port input buffer AUTOLVL configuration register */
   __IM uint32_t RESERVED2[9];
} GPIO_PRT_V2_Type;                             /*!< Size = 128 (0x80) */

Then If you look to the Register TRM, you will see that there is no register at address 0x40310050 described. Last described of PRT1 module is at offset 0x4C.

I asked at Cypress Community (https://community.cypress.com/message/267587) about it. Answer was that reason for it is some reservation for feature use and register do not exists in chip while it is referred in PDL code.

Similarly, there are (probably?) undescribed features in Architecture TRM. For example, USB block has USBFS0_USBDEV_OSCLK_DR0 register with description “Oscillator lock data register 0” but in Architecture TRM there is no description of any oscillator lock feature. I think that Cypress should spend some time to make a lot of features described in more detail.

Unless undescribed features TRM is good document and I like it. It is well structured and written by humans for humans. TRM notices lot of things in very familiar way. For example, I can note recommendation for I2C pullups which are described without long description of rocket science and Cypress’s description makes sense.

Next thing I like in Register TRM is navigation. At beginning of every chapter is table describing all relevant registers. All registers contain absolute address which is good when you are searching for some information in some debug state or when you are reversing firmware. If you have read chapter Review of Microcontroller you know that PSoC is not a just MCU, it is chip containing multiple blocks interconnected in interesting way, but some same blocks differ a little. In navigation menu provided by PDF reader you can simply see determine how blocks differs without directly searching for them. As you can see at following screenshot duplicate registers are not mentioned in menu. You can very simply guess that for example register related to PORT1 matches the same structure as PORT0 just from seeing menu. Similarly, you can guess that register related to GPIO port 2 differs from port 0 (and 1).

Programming manual (specification)

Programming manual Is document with detailed information related to flashing firmware, memory layouts and similar things. It does not contain any description of instruction set. Instruction set you must search at ARM website if you are interested in detail about it. I found some minor mistakes in that document. For example, memory layout mention that you can use 128GB (yes, GB) for XIP technology. This is totally non-sense because whole 32 bit range allows for addressing only 4 GB (GiB to be clear) of data. Author of document mistaken the units. Correct value is 128MB (MiB to be clear).

4 pages later there are mentioned that application is sized up to 1 MB but in fact roadtested unit has 2MiB Flash. In the text below the image, it is correct. They probably forget to update that number when they announced first chip with more than 1 MB of flash.

But except that minor issues that document is good. You probably never want to read him but when needed it is ok.

Documentation of Wi-Fi Module

WiFi + BLE chip is CYW43012. Originally it was named BCM43012 and it came from Broadcom. But Cypress acquired part of Broadcom responsible for 43012. Previous sentence contains one good news. While Broadcom do not release almost any documentation publicly excluding some marketing brochures. Cypress is much more open to world with documentation. For chip there are available datasheet. No TRM or something similar. Datasheet is detailed and contains overview and characteristics of chip. Described are both BLE and WiFi part of chip. Chip is part of Murata Type 1LV module (which in fact also looks like chip in white/grey package) and it has also some documentation. But it is very brief. I do not worry about documentation for WiFi + BLE chip a lot because almost nobody need it. Basic parameters are presented in datasheet and other things are implemented in libraries. WIFi + BLE module is very complex thing and you probably never will work it so low level to require any advanced documentation. There are documentation for WiFi and BLE related libraries. I will describe it later in this article.

Documentation of KitProg3

There is some documentation for KitProg3. It is sometimes shared also for MiniProg4 (this is dedicated version of onboard KitProg3). Most important information you find at webpage named “KitProg user guide”. At the bottom of that page is available PDF with some instructions how to use it. I used KitProg intuitively because I have experiences with similar debuggers. It may be useful for some troubleshooting (for example driver issues) or beginners may consider it useful.

Documentation of FLASH and FRAM

FLASH and FRAM documentation is present in datasheet. Datasheets are easy to find. Because flash comes from acquired vendor, datasheet was also written by original company. It has different chapter structure than FRAM datasheet, but I have no issue with both documents. They are good and easy to read. I did not find any undescribed feature. I oriented quicky in both datasheets.

Documentation of Software Libraries used in development

The best of all Cypress documentation is documentation for software libraries (PDL, HAL and other ported libraries like libraries for WiFi, BLE and also smaller libraries like serial-flash, retarget-io and rgb-led). You can find links to offline copy of documentation in Quick Panel in ModusToolbox IDE. Documentation is made using Doxygen and it contains not just brief documentation to functions generated from comments but contains a lot of texts. This documentation is available for almost every library provided by Cypress including peripheral and board specific libraries. Documentation is also available online. The most useful part of this documentation are main pages of every section. For example, for the PDL library you can see documentation for using serial communication block (SCB) in I2C mode. At main page of this section (https://cypresssemiconductorco.github.io/psoc6pdl/pdl_api_reference_manual/html/group__group__scb__i2c.html) you can see everything what you need including text description and code examples how to make I2C working in minimal way. All functions are properly documented. I think that this documentation makes development even simpler than reading integrated code examples in IDE. Documentation is generated from comments so you can see the same description (for functions, macros, structs, …) when Ctrl + click on its name in IDE. I like that documentation very much. You can use it as a single source of information and do not need worry about any PDFs if you want.

Github

Cypress actively publish lot of examples to github. All examples available which you can create in ModusToolbox IDE are available at github. In fact, ModusToolbox downloads them from github. Every GitHub repository contains a README.md which I consider also as documentation because it contains a lot of useful information about example. I like that and I used https://github.com/cypresssemiconductorco/ a lot when roadtesting.

To summarize: PDFs are acceptable, Doxygen documentation is fantastic and code examples are great. I like that documentation while there are some points which could be improved from Cypress side.