Tilt Hydrometer (Part 1) Overview & Out-of-Box

Summary

A discussion of a new series of articles about using the PSoC 6 + 43XXXX Wifi/Bluetooth combo chips to implement a data collection system for the Tilt2 Hydrometer.  Even if you aren’t specifically interested in hydrometers, this is a general purpose discussion of the design of an IoT device.

Story

In the middle of the Covid lockdown my 21-year-old daughter suggested that we start brewing beer.  This was always something that I have been interested in so I said “Sure!”.  What does this have to do with IoT you might ask?  I am an engineer and I love data.  Two of the key pieces of data that you are interested in while fermenting beer are:

  • The gravity of the beer
  • The temperature of the beer

If you don’t know anything about brewing beer, it is simple (people have been doing it a long time… even with no IoT)

  1. Start with grain
  2. Mill the grain
  3. Heat the grain with water to turn it into sugar water (called wort)
  4. Add yeast
  5. Wait while the yeast converts the sugar in the wort into alcohol and carbon dioxide
  6. Bottle the beer (or keg)
  7. Drink

Back to the metrics.  The “specific gravity” or just “gravity” is just the ratio of the density of your solution to plain water.  This is an indication of sugar in the wort solution.  At the start of the fermentation you will have “lots” of sugar, and no alcohol.  By the end you will have “lots” of alcohol and not much sugar.  You can tell how things are going by monitoring the gravity of the beer, which is a proxy metric for how much sugar has been converted to alcohol.

There are two common ways to measure the gravity:

  • A float hydrometer – sugar water is denser then water, so a “float” will float lower in the solution as the sugar gets converted to alcohol.
  • A refractometer – the index of refraction of the solution changes as the sugar concentration changes (this is an amazing old-school technology

As I was learning about this whole process I found the tilt hydrometer.  This device has

As the gravity of the beer changes, the device floats at a different angle (because it floats lower/higher).  They use the accelerometer to measure the apparent angle of gravity to calculate the angle of the device.  This angle is then used to calculate the density of the solution it is floating in.  They then broadcast the calculated gravity and temperature in Apple Bluetooth iBeacon format.

When I saw this, I thought “perfect” I know what to do with that.  I should build a device that can collect all of the data, display it, save it to an SPI flash and put it into the cloud.  It should look something like this: (each Tilt is identified by 1 of 8 colors… pink in this case).

Yes, I know they have an iPhone app, but I want to build a single device that sits in my brewery all of the time.  And yes I know they have a Raspberry Pi app, but that isn’t the point.

My device will have the following characteristics:

A Display with:

  • A Splash Screen
  • A Table of all Tilts, Gravity and Temperature
  • Single: One screen per tilt with the specific data including debugging
  • Single: A graph of the active data for one specific tilt
  • Single: A table of all of the recordings from that specific tilt
  • The WiFi Status
  • The Bluetooth Status

Bluetooth System that can:

  • Record tilt data as broadcast in iBeacon advertising packets
  • Repeat tilt data (maybe)
  • Introducer WiFi (probably)

CapSense button GUI to:

  • Next Screen
  • Auto Mode
  • Reset current
  • Dump recorded data to the SD Card

Command Line

  • A UART based command line to debug & learn

USB

  • Mass Storage to see files
  • USB <-> UART Bridge

Power Supply via USB Port

  • Plug in Type-C using Cypress BCR

WiFi

  • MQTT Publish to AWS
  • NTP – to find the time
  • Local webserver
  • MDNS

RTC

  • Keep Track of current Time

SPI NOR Flash

  • Record the data

SD CARD

  • Dump the fixed SPI Flash  recordings to a removable SD CARD & remove data from the SPI Flash

Here is another picture of what I am thinking (well actually what I implemented for this series of articles)

Un-boxing

To get this show on the road, I ordered three tilts and two repeaters from Baron Brew Equipment.

It included a neat little quick start picture showing how to get going.

Then the box of goodies.

There are 8-possible tilts, Red, Green, Orange, Blue, Black, Yellow, Purpose and Pink (each Tilt his “hardcoded” to identify itself as a specific color)

Tilt Hydrometer

Here is a picture of the “blue” one (notice I put the wrong box in the picture)

The tilt comes in a plastic tube.  Which has a label to remind you to take it out of the tube (my experience is that you should be embarrassed to have to read most warning labels 🙂 )

It is about 100mm long (about 4 inches).  The bluetooth module is at the top, U3 is the temperature sensor and U2 (which is under the black 3-d printed plastic) is the accelerometer.

Repeater

If you put a Bluetooth device floating in a bunch of beer, surrounded by a metal fermentation container, you will not be able to hear the Bluetooth signal.  To solve this problem the Tilt people made a repeater which can rest on the top of the fermenter.  It listens for the weak signal, then rebroadcasts with a higher gain antenna.

Here is a picture of the repeater.  Notice that it uses the BMD-301 which has an external SMA antenna.

It also comes in a nice plastic tube.

The repeater can only re-broadcast one color at a time.  The button to switches between the 8 colors and off.

Each time you press the button the 3-color LED lights up with the color that represents which tilt color that it is repeating. Red->Green->… Pink->Off

It also has a huge rechargeable battery.

The Plan

Here is a list of the articles that I plan to write

This series is broken up into the following 12 articles with a few additional possible articles. 

Tilt Hydrometer (Part 1) Overview & Out-of-Box

Tilt Hydrometer (Part 2) Architecture

Tilt Hydrometer (Part 3) Advertising Scanner

Tilt Hydrometer (Part 4) Advertising Packet Error?

Tilt Hydrometer (Part 5) Tilt Simulator & Multi Advertising iBeacons

Tilt Hydrometer (Part 6) Tilt Simulator an Upgrade

Tilt Hydrometer (Part 7) Advertising Database

Tilt Hydrometer (Part 8) Read the Database

Tilt Hydrometer (Part 9) An LCD Display

Tilt Hydrometer (Part 10) The Display State Machine

Tilt Hydrometer (Part 11) Draw the Display Screens

Tilt Hydrometer (Part 12) CapSense

Tilt Hydrometer: LittleFS & SPI Flash (Part ?)

Tilt Hydrometer: WiFi Introducer (Part ?)

Tilt Hydrometer: WebServer (Part ?)

Tilt Hydrometer: Amazon MQTT (Part ?)

Tilt Hydrometer: Printed Circuit Board (Part ?)

You can get the source code from git@github.com:iotexpert/Tilt2.git  This repository has tags for each of the articles which can be accessed with "git checkout part12"  You can find the Tilt Simulator at  git@github.com:iotexpert/TiltSimulator.git.

 

AnyCloud Bluetooth Advertising Scanner (Part 8)

Summary

In this series of articles I am building a Bluetooth Low Energy Scanner using the Cypress/Infineon AnyCloud SDK running on a PSoC 6 and CYW43xxx.  In Part 8 I will turn on the ability to filter duplicate advertising packets.

Story

In the previous article I added the ability to record advertising packets.  The problem is, of course, that many devices are blasting out advertising packets, which will quickly overwhelm you.  I suppose more importantly it will overwhelm the packet buffer.  Most of the device are just advertising their presence, so they send the same data over and over.  Some devices alternate between a small number of different advertising packets, e.g. an iBeacon then and Eddystone beacon.

The way that the filter will work is that I will update the “add” function to search through all of the packets that device has launched, then if I have seen the packet before (Ill use a memcmp) then I will just keep a count of how many times I have see that packet.

The other thing that needs to happen is for me to add a “filter” command so that I can turn on packet filtering on a device by device basis.

And I need to fix the printing to use the new filtered packet database.

There are

Article Topic
AnyCloud Bluetooth Advertising Scanner (Part 1) Introduction to AnyCloud Bluetooth Advertising
AnyCloud Bluetooth Advertising Scanner (Part 2) Creating an AnyCloud Bluetooth project
AnyCloud Bluetooth Advertising Scanner (Part 3) Adding Observing functionality to the project
AnyCloud Bluetooth Utilities Library A set of APIs for enhancement of the AnyCloud Library
AnyCloud Bluetooth Advertising Scanner (Part 4) Adding a command line to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 5) Adding a history database to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 6) Decoding advertising packets
AnyCloud Bluetooth Advertising Scanner (Part 7) Adding recording commands to the command line
AnyCloud Bluetooth Advertising Scanner (Part 8) Adding filtering to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 9) Improve the print and add packet age
AnyCloud Bluetooth Advertising Scanner (Part 10) Sort the database

All of the code can be found at git@github.com:iotexpert/AnyCloudBLEScanner.git and https://github.com/iotexpert/AnyCloudBLEScanner.git

There are git tags in place starting at part 5 so that you can look at just that version of the code.  "git tag" to list the tags.  And "git checkout part6" to look at the part 6 version of the code.

You can also create a new project with this is a template if you have the IoT Expert Manifest Files installed

Update the Data Structures

In order to do the filters, and keep track of the data I will add

  1. A “count” field to the packet data structure
  2. A “filter” boolean field to the device data structure.
typedef struct {
    uint8_t *data;
    int count;
    struct adb_adv_data_t *next;
} adb_adv_data_t;

typedef struct {
    wiced_bt_ble_scan_results_t *result;
    bool record;
    bool filter;
    int numSeen;
    int listCount;
    adb_adv_data_t *list;
} adb_adv_t ;

Update the Add Function

In the function “static void adb_db_add(wiced_bt_ble_scan_results_t *scan_result,uint8_t *data)” which is called every time I see a new advertising packet I will need to handle four different cases:

  1. The first time you see a device
  2. A device you have seen AND you are recording AND have the filtering turned on
  3. A device you are recording but not filtering
  4. A device you have seen, but are not recording or filter.

In the first case, a device you haven’t seen before, you need to

  1. Automatically turn on the filtering
  2. Initialize the counts to 1
  3. Do the other initialization (as before)
    // If it is NOT found
    if(entry == -1)
    {
        adb_database[adb_db_count].result = scan_result;
        adb_database[adb_db_count].listCount = 1;
        adb_database[adb_db_count].record = false;
        adb_database[adb_db_count].filter = true;
        adb_database[adb_db_count].numSeen = 1;

        adb_adv_data_t *current = malloc(sizeof(adb_adv_data_t));
        current->next = 0;
        current->data = data;
        current->count = 1;

In the case where you have

  1. See the device before
  2. You have room in the record buffer
  3. And you are in record mode

You will then decide if you are filtering.

Then you will iterate through all of the packets and compare the data to the data you just received.  If there is a match then you update the count, free the duplicate data and return.

    else if(adb_database[entry].record && adb_recording_count<ADB_RECORD_MAX && adb_recording)
    {
        adb_database[entry].numSeen += 1;

        if(adb_database[entry].filter) // if filtering is on.
        {
            int len = btutil_adv_len(data); 
            for(adb_adv_data_t *list = adb_database[entry].list;list;list = (adb_adv_data_t *)list->next)
            {
                if(memcmp(list->data,data,len) == 0) // Found the data
                {
                    list->count += 1;
                    printf("Count = %d\n",list->count);
                    free(data);
                    free(scan_result);
                    return;
                }
            }
        }

If you have not see the data before, then you need to add it to the linked list.

        adb_adv_data_t *current = malloc(sizeof(adb_adv_data_t));
        current->next = (struct adb_adv_data_t *)adb_database[entry].list;
        current->data = data;
        current->count = 1;

If you are not recording and not filtering, just increment counts.

    else
    {
        adb_database[entry].numSeen += 1;
        adb_database[entry].list->count += 1;

Add a “filter” Command

I want the ability for a user to “filter all” or “filter clear” or “filter #” – just like we did with watch.  So, add the #defines and new function to advDatabase.h

#define ADB_FILTER_ALL -1
#define ADB_FILTER_CLEAR -2
void adb_filter(int entry);

Then add the new filter command in advDatabase.c

typedef enum {
    ADB_ADD,
    ADB_PRINT_RAW,
    ADB_PRINT_DECODE,
    ADB_WATCH,
    ADB_ERASE,
    ADB_RECORD,
    ADB_FILTER,
} adb_cmd_t;

I will use the adb_queueCmd function that I created in the last article.

inline void adb_filter(int entry) { adb_queueCmd(ADB_FILTER,(void*)entry,(void *)0); }

The filter command has three cases

  1. All – turn the bool for all on
  2. Clear – turn the bool for all off
  3. Just a specific number – toggle that specific number
static void adb_db_filter(int entry)
{
    if(entry == ADB_FILTER_ALL)
    {
        for(int i=0;i<adb_db_count;i++)
        {
            adb_database[i].filter = true;
        }
        return;
    }

    if(entry == ADB_FILTER_CLEAR)
    {
        for(int i=0;i<adb_db_count;i++)
        {
            adb_database[i].filter = false;
        }
        return;
    }

    if(entry > adb_db_count-1 || entry < ADB_WATCH_CLEAR)
    {
        printf("Record doesnt exist: %d\n",entry);
        return;      
    }
    adb_database[entry].filter = !adb_database[entry].filter; 

}

And you need to fix up the main command processor

                case ADB_FILTER:
                    adb_db_filter((int)msg.data0);
                break;

Finally add the command to the usrcmd.c

static int usrcmd_filter(int argc, char **argv)
{

    if(argc == 2 && !strcmp(argv[1],"all"))
    {
        adb_filter(ADB_FILTER_ALL); // all
        return 0;
    }


    if(argc == 2 && !strcmp(argv[1],"clear"))
    {
        adb_filter(ADB_FILTER_CLEAR);
        return 0;
    }

    if(argc == 2)
    {
        int i;
        sscanf(argv[1],"%d",&i);
        adb_filter(i);
        return 0;
    }

    return 0;
}

Fix the Printing

Now we nee to fix the printing.  I want to add an indicate of the filtering to the output.  Remember from the previous article I indicated “Watch” with a “*”.  When I looked at it, I decided that I should indicate filter with an “F” and watch with a “W”.  So I fix that.

        printf("%c%c%02d %05d %03d MAC: ",adb_database[i].record?'W':' ',
            adb_database[i].filter?'F':' ',
            i,adb_database[i].numSeen,adb_database[i].listCount);
        btutil_printBDaddress(adb_database[i].result->remote_bd_addr);
        switch(method)
        {

Then I test the “filter” command

Fix the Printing Part (2)

As I noodled on how to change the printing I decide that it would be nice to sometimes print out only one packet e.g. no history and sometimes print them all out e.g. history.  So, I add a new parameter to the function called “history”

static void adb_db_print(adb_print_method_t method,bool history,int entry)

As I looked at the printing code, I decided that it would be better to have a new function to print only one entry.  I suppose that I could have left the code inline, but I thought that intent was clearer.

static void adb_db_printEntry(adb_print_method_t method, int entry, adb_adv_data_t *adv_data)
{
    printf("%c%c%02d %05d %03d MAC: ",adb_database[entry].record?'W':' ',
    adb_database[entry].filter?'F':' ',
    entry,adb_database[entry].numSeen,adb_database[entry].listCount);
    btutil_printBDaddress(adb_database[entry].result->remote_bd_addr);

    switch(method)
    {
    
    case ADB_PRINT_METHOD_BYTES:
        printf(" Data: ");
        btutil_adv_printPacketBytes(adv_data->data);
    break;

    case ADB_PRINT_METHOD_DECODE:
        printf("\n");
        btutil_adv_printPacketDecode(adv_data->data);
    break;
    } 
    printf("\n");

}

With the new function in place I now need to update the print function to call the new entry function.  Printing the history is just a matter of iterating through the linked list.

static void adb_db_print(adb_print_method_t method,bool history,int entry)
{
    int start,end;
 
    if(entry < 0)
    {
        start = 0;
        end = adb_db_count;
    }
    else
    {
        start = entry;
        end = entry+1;
    }

    if(end>adb_db_count)
        end = adb_db_count; 

    for(int i=start;i<end;i++)
    {
        if(history) // then iterate through the linked list print all of the packets
        {
            for(adb_adv_data_t *list = adb_database[i].list;list;list = (adb_adv_data_t *)list->next)
            {
                adb_db_printEntry(method,i,list);    
            }
        }
        else // Just print the first packet in the list
            adb_db_printEntry(method,i,adb_database[i].list);
    }
}

Now, I need to update all of the calls to adb_db_print to have the new history parameter.  First, I made the decision that when you “print” from the command line that you are interested in the history.

                case ADB_PRINT_RAW:
                    adb_db_print(ADB_PRINT_METHOD_BYTES,true,(int)msg.data0);
                break;
                case ADB_PRINT_DECODE:
                    adb_db_print(ADB_PRINT_METHOD_DECODE,true,(int)msg.data0);
                break;

But when you are printing out the packet for a new device don’t print out the history

            adb_db_print(ADB_PRINT_METHOD_BYTES,false,adb_db_count-1);

Program and Test

After I program my development kit, I start by typing “watch all”.  Very quickly, at my house, you can see that a bunch of devices are discovered.  You can see that all of these have a “W” (meaning that I am watching them) and an “F” meaning they are filtering out duplicates.  Then I type “record” to turn on recording. After a minute I turn off recording then do the print you can see below.

A couple of things to notice.

  1. Device #4 (which I highlighted) appears to be sending out a pattern of alternating packets.  See that I have heard 3335 packets yet there are only two in the buffer
  2. You can see device 11 seems to be sending out 16 different packets.  Why?  I don’t know.

But we can “decode 11” to try to figure it out.  You can see that it is advertising manufactures specific data with Apple’s UUID which I happen to know is 0x004C.  But why?  I don’t know.

I really want to move onto a new series of articles… but there are two functions which I will add to the program.  Stay tuned for what they do.

AnyCloud Bluetooth Advertising Scanner (Part 7)

Summary

In this series of articles I am building a Bluetooth Low Energy Scanner using the Cypress/Infineon AnyCloud SDK running on a PSoC 6 and CYW43xxx.  In Part 7 I will add the ability to record BLE ADV packets.

Story

If you have been reading along, at this point we have built a BLE scanner that can see Bluetooth devices that are advertising.  My scanner has a command line and you can print out the most recent data.  Even better, we built a decoder that allows you to better understand the data.

Now I want to add the ability to record more than one advertising packet per device.  To that end I will add three commands:

  • watch – Mark a device as one that needs to have the advertising data recorded.  You can type “watch 12” or you can say “watch all” or you can say “watch clear”
  • record – Turn on recording of “watched” devices.  When you type record it will toggle the recording state between On and Off.
  • erase – clear the record buffer of all but the most recent packet.

There are

Article Topic
AnyCloud Bluetooth Advertising Scanner (Part 1) Introduction to AnyCloud Bluetooth Advertising
AnyCloud Bluetooth Advertising Scanner (Part 2) Creating an AnyCloud Bluetooth project
AnyCloud Bluetooth Advertising Scanner (Part 3) Adding Observing functionality to the project
AnyCloud Bluetooth Utilities Library A set of APIs for enhancement of the AnyCloud Library
AnyCloud Bluetooth Advertising Scanner (Part 4) Adding a command line to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 5) Adding a history database to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 6) Decoding advertising packets
AnyCloud Bluetooth Advertising Scanner (Part 7) Adding recording commands to the command line
AnyCloud Bluetooth Advertising Scanner (Part 8) Adding filtering to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 9) Improve the print and add packet age
AnyCloud Bluetooth Advertising Scanner (Part 10) Sort the database

All of the code can be found at git@github.com:iotexpert/AnyCloudBLEScanner.git and https://github.com/iotexpert/AnyCloudBLEScanner.git

There are git tags in place starting at part 5 so that you can look at just that version of the code.  "git tag" to list the tags.  And "git checkout part6" to look at the part 6 version of the code.

You can also create a new project with this is a template if you have the IoT Expert Manifest Files installed

Update the advDatabase Interface

The first thing I realized as I went to add a new command was that I was typing the exact same code over and over for the public interface.  The code looked like this:

void adb_watch(int entry)
{
    adb_cmdMsg_t msg;
    msg.cmd = ADB_WATCH;
    msg.data0 = (void *)entry;
    xQueueSend(adb_cmdQueue,&msg,0); // If the queue is full... oh well

}

So I created this:

static void adb_queueCmd(adb_cmd_t cmd,void *data0, void *data1)
{
    adb_cmdMsg_t msg;
    msg.cmd = cmd;
    msg.data0 = data0;
    msg.data1 = data1;
    xQueueSend(adb_cmdQueue,&msg,0); // If you loose an adv packet it is OK...
}

Then did this to eliminate the duplication.

inline void adb_addAdv(wiced_bt_ble_scan_results_t *scan_result,void *data) { adb_queueCmd(ADB_ADD,(void *)scan_result,(void *)data);}
inline void adb_print(int entry) { adb_queueCmd(ADB_PRINT_RAW,(void *)entry,(void *)0); }
inline void adb_decode(int entry) { adb_queueCmd(ADB_PRINT_DECODE,(void*)entry,(void *)0); }

Redo the Database

If you recall from previous posts, my advertising database was just

  1. An Array of structures
  2. Each structure contained the mac address and…
  3. A pointer to a malloc’d copy of the advertising data
typedef struct {
    wiced_bt_ble_scan_results_t *result;
    uint8_t *data;
} adb_adv_t ;

#define ADB_MAX_SIZE (40)
adb_adv_t adb_database[ADB_MAX_SIZE];

Here is a picture of the datastructure

 

Now what I want to do is make the “data” pointer to be a pointer to a linked list of data.  Here is the new definition.

typedef struct {
    uint8_t *data;
    struct adb_adv_data_t *next;
} adb_adv_data_t;

typedef struct {
    wiced_bt_ble_scan_results_t *result;
    int listCount;
    bool record;
    int numSeen;
    adb_adv_data_t *list;
} adb_adv_t ;

The new data structure looks like this

I wanted to limit the number advertising packets that can be stored so I don’t run out of memory.  I am not actually sure how many can be stored, but I suppose a bunch as the chip has 1MB of RAM.  But, I pick 100 which seems like enough to start out with.  I create two variables

  1. A counter for the number of advertising packets that are currently saved
  2. A recording state (are you saving or not)
#define ADB_RECORD_MAX (100)
static int adb_recording_count = 0;
static bool adb_recording = false;

Update the Printing

You probably noticed that I declared two new members of the adb_adv_t structure, specifically numSeen and listCount, which I would like to print out.   I also wanted a visual indication that I am “watching” a device.  The columns are now:

  1. A “*” to indicate that a device is being watched
  2. The device #
  3. The number of packets that I have seen in total from that device
  4. The number of recorded packets for that device
  5. The MAC address
  6. The raw bytes

To do implement this a simple change is made to the print function:

    for(int i=start;i<end;i++)
    {
    
        printf("%s%02d %05d %03d MAC: ",adb_database[i].record?"*":" ",i,adb_database[i].numSeen,adb_database[i].listCount);
        btutil_printBDaddress(adb_database[i].result->remote_bd_addr);
        switch(method)
        {
        
        case ADB_PRINT_METHOD_BYTES:
            printf(" Data: ");
            btutil_adv_printPacketBytes(adb_database[i].list->data);
        break;

        case ADB_PRINT_METHOD_DECODE:
            printf("\n");
            btutil_adv_printPacketDecode(adb_database[i].list->data);
        break;
        } 
        printf("\n");
    }

Update the Add

Now that we have all of the infrastructure in place we need to update the function that saves advertising data.  When an advertising packet comes in you have three situations to consider:

  1. You have never seen the device before
  2. You have seen the device before and you are “watching” it
  3. You have see the device but you are not watching it

In the case where you have never seen the device you need to

  1. Save the scan result
  2. Set the listCount to 1 (you only have one datapoint)
  3. Turn off recording (start with the recording off)
  4. Set the total numSeen to 1 as this is the first packet you have seen
  5. Allocate some memory for the advertising linked list structure
  6. Terminate the linked list
  7. Save the advertising data
  8. Increment the database count (up to the max)
  9. Print out the packet you just saw
    if(entry == -1)
    {
        adb_database[adb_db_count].result = scan_result;
        adb_database[adb_db_count].listCount = 1;
        adb_database[adb_db_count].record = false;
        adb_database[adb_db_count].numSeen = 1;

        adb_adv_data_t *current = malloc(sizeof(adb_adv_data_t));
        current->next = 0;
        current->data = data;

        adb_database[adb_db_count].list = current;

        adb_db_count = adb_db_count + 1;
        if(adb_db_count == ADB_MAX_SIZE)
        {
            printf("ADV Table Max Size\n");
            adb_db_count = adb_db_count - 1;
        }
        else
        {    
            adb_db_print(ADB_PRINT_METHOD_BYTES,adb_db_count-1);
        }
    }

In the case where you have

  1. Seen the device before
  2. You are recording that device
  3. There is room left in the recording buffer

Then you will

  1. Increment number seen
  2. Create memory for the new entry in the linked list
  3. Attach the tail of the linked list to your new entry (you will insert at the front of the list)
  4. Save the data
  5. Increment the number of saved entries
  6. Insert your new packet at the head of the list
  7. Printout the packet
  8. Increment the record count (the total number of packets in the recording buffer)
  9. Then potentially stop recording if you have gotten to the max size.
    else if(adb_database[entry].record && adb_recording_count<ADB_RECORD_MAX && adb_recording)
    {
        adb_database[entry].numSeen += 1;

        adb_adv_data_t *current = malloc(sizeof(adb_adv_data_t));
        current->next = (struct adb_adv_data_t *)adb_database[entry].list;
        current->data = data;
        adb_database[entry].listCount += 1;
        adb_database[entry].list = current;

        adb_db_print(ADB_PRINT_METHOD_BYTES,entry);

        adb_recording_count += 1;
        if(adb_recording_count == ADB_RECORD_MAX)
        {
            adb_recording = false;
            printf("Recording buffer full\n");
        }
    }

In the case where you have seen the device before, but you are not recoding then you will

  1. Update the numSeen
  2. Erase the old packet data
  3. Save the new packet
  4. Erase the “result” (you already have it saved)
    else
    {
        adb_database[entry].numSeen += 1;
        free(adb_database[entry].list->data);
        adb_database[entry].list->data = data;
        free(scan_result);
    }

Add a Watch Command

The watch function is pretty simple.  It just needs to either mark the “record” boolean as true or false.  When I decided to implement this function I decided to make positive numbers be the entry in the table.  But, I also wanted to be able to “watch all” and “watch clear”.  So, I used negative numbers for those two special meanings.  I used a #define in advDatabase.h to define those values.

#define ADB_WATCH_ALL -1
#define ADB_WATCH_CLEAR -2

The function is then pretty simple

  1. If it is watch all… then iterate through the database and turn them on
  2. If it is watch clear … then iterate through the database and turn them off
  3. Otherwise make sure that it is a legal number and toggle it.
static void adb_db_watch(int entry)
{
    if(entry == ADB_WATCH_ALL)
    {
        for(int i=0;i<adb_db_count;i++)
        {
            adb_database[i].record = true;
        }
        return;
    }

    if(entry == ADB_WATCH_CLEAR)
    {
        for(int i=0;i<adb_db_count;i++)
        {
            adb_database[i].record = false;
        }
        return;
    }

    if(entry > adb_db_count-1 || entry < ADB_WATCH_CLEAR)
    {
        printf("Record doesnt exist: %d\n",entry);
        return;      
    }
    adb_database[entry].record = !adb_database[entry].record; 

}

Once I have the infrastructure in place, I then add the watch command to usrcmd.c

static int usrcmd_watch(int argc, char **argv)
{

    if(argc == 2 && !strcmp(argv[1],"all"))
    {
        adb_watch(ADB_WATCH_ALL); // all
        return 0;
    }


    if(argc == 2 && !strcmp(argv[1],"clear"))
    {
        adb_watch(ADB_WATCH_CLEAR);
        return 0;
    }

    if(argc == 2)
    {
        int i;
        sscanf(argv[1],"%d",&i);
        adb_watch(i);
        return 0;
    }

    return 0;
}

Add a Record Command

The record command simply turns on the global bool to either true or false and prints out the number of spaces free in the record “buffer”

                case ADB_RECORD:
                    adb_recording = !adb_recording;
                    printf("Record %s Buffer Entries Free=%d\n",adb_recording?"ON":"OFF",
                        ADB_RECORD_MAX-adb_recording_count);
                break;

And the change to usrcmd.c is also simple.

// record = toggles
static int usrcmd_record(int argc, char **argv)
{
    if(argc == 1)
    {
        adb_record(-1);
        return 0;
    }
    return 0;
}

Add an Erase Command

The erase function is like “watch”, as I overload the “entry” to have an ALL which is setup in advDatabase.h

#define ADB_ERASE_ALL -1

The erase is a bit more complicated than the watch.  When you receive a erase command you will either erase them all by iterating over the whole dates, or just erase one.

                case ADB_ERASE:
                    if((int)msg.data0 == ADB_ERASE_ALL)
                    {
                        for(int i=0;i<adb_db_count;i++)
                        {
                            adb_eraseEntry(i);
                        }
                    }
                    else
                        adb_eraseEntry((int)msg.data0);

                    printf("Record Buffer Free %d\n",ADB_RECORD_MAX-adb_recording_count);
                break;

The individual eraseEntry function checks to make sure that you have a legal “entry”.  Then it follows the linked list “freeing” the data structures.

static void adb_eraseEntry(int entry)
{
    if(entry > adb_db_count-1 || entry<0)
    {
        printf("Erase Entry Not Found %d\n",entry);
        return;
    }

    adb_adv_data_t *ptr;
    ptr = (adb_adv_data_t *)adb_database[entry].list->next;
    adb_database[entry].list->next = 0;
    while(ptr)
    {
        adb_adv_data_t *next;
        next = (adb_adv_data_t *)ptr->next;
        free(ptr->data);
        free(ptr);
        adb_database[entry].listCount -= 1;
        adb_recording_count -= 1;
        ptr = next;
    }
}

And, of course, you need to add the command to usrcmd.c

// erase
// erase #
static int usrcmd_erase(int argc, char **argv)
{
    if(argc > 2)
    {
        return 0;
    }

    if(argc == 1)
    {
        adb_erase(ADB_ERASE_ALL);
        return 0;
    }

    int i;
    sscanf(argv[1],"%d",&i);
    adb_erase(i);
    return 0;    

}

Now when you build and program the kit you can turn on/off recording and erase and….

In the next post I will add

  1. Smarter printing
  2. A “filter” to eliminate duplicate advertising packets

AnyCloud Bluetooth Advertising Scanner (Part 6)

Summary

In part 6 of this series I will update the AnyCloud BLE Advertising Scanner to decode advertising packets into a more human readable textual output

Story

We are now 6 (or maybe 7 depending on how you count) articles into this series and we are still looking at raw bytes.  I have gotten to where I am pretty good at understanding those bytes, but that is now way to roll.  You might remember from the article on the IoT Expert Bluetooth Utility library that there were a some interesting functions defined in the header.  Here it is:

wiced_bool_t btutil_isEddystone(uint8_t *data);
wiced_bool_t btutil_is_iBeacon(uint8_t *data);
wiced_bool_t btutil_isCypress(uint8_t *data);

int btutil_adv_len(uint8_t *packet);
void btutil_adv_printPacketDecode(uint8_t *packet);
void btutil_adv_printPacketBytes(uint8_t *packet);

Lets transform our  project from part 6 to use these functions.  In this article I will

  • Redo the print bytes (to be smarter) functionality and to use the built in function
  • Rework the logic for the “print” command implementation
  • Add a new command “decode” which will run the decode function

There are

Article Topic
AnyCloud Bluetooth Advertising Scanner (Part 1) Introduction to AnyCloud Bluetooth Advertising
AnyCloud Bluetooth Advertising Scanner (Part 2) Creating an AnyCloud Bluetooth project
AnyCloud Bluetooth Advertising Scanner (Part 3) Adding Observing functionality to the project
AnyCloud Bluetooth Utilities Library A set of APIs for enhancement of the AnyCloud Library
AnyCloud Bluetooth Advertising Scanner (Part 4) Adding a command line to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 5) Adding a history database to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 6) Decoding advertising packets
AnyCloud Bluetooth Advertising Scanner (Part 7) Adding recording commands to the command line
AnyCloud Bluetooth Advertising Scanner (Part 8) Adding filtering to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 9) Improve the print and add packet age
AnyCloud Bluetooth Advertising Scanner (Part 10) Sort the database

All of the code can be found at git@github.com:iotexpert/AnyCloudBLEScanner.git and https://github.com/iotexpert/AnyCloudBLEScanner.git

There are git tags in place starting at part 5 so that you can look at just that version of the code.  "git tag" to list the tags.  And "git checkout part6" to look at the part 6 version of the code.

You can also create a new project with this is a template if you have the IoT Expert Manifest Files installed

Replace two code blocks with function calls

Do you remember this block of code?  It print’s out the 6-bytes of the Bluetooth Address.

    for(int i=0;i<BD_ADDR_LEN;i++)
    {
        printf("%02X:",adb_database[entry].result->remote_bd_addr[i]);
    }

You might have noticed that this function already exists in the BT Utility Library.  Use it.

    btutil_printBDaddress(adb_database[entry].result->remote_bd_addr);

Then you remember this block of code which iterates through and advertising packet and prints out the raw bytes?

// Print the RAW Data of the ADV Packet
    printf(" Data: ");
    int i=0;
    while(adb_database[entry].data[i])
    {
        for(int j=0;j<adb_database[entry].data[i];j++)
        {
            printf("%02X ",adb_database[entry].data[i+1+j]);
        }
        i = i + adb_database[entry].data[i]+1;
    }

Well, it exists in the library as well.  Use it.

btutil_adv_printPacketBytes(adb_database[entry].data);

Fix the “print” Command

In the previous implementation I had two functions for “print”.  The first one printed one entry and the second one printed the whole table.  I decided that I didnt really like this logic, so I compressed those two functions into one function.  Specifically, it take a number “entry”.  If that number is -1 then it will print the whole table.

static void adb_db_printRawPacket(int entry)
{
    int start,end;
 
    if(entry <= -1)
    {
        start = 0;
        end = adb_db_count;
    }
    else
    {
        start = entry;
        end = entry;
    }

    if(end>adb_db_count)
        end = adb_db_count; 

    for(int i=start;i<=end;i++)
    {
    
        printf("%02d MAC: ",i);
        btutil_printBDaddress(adb_database[i].result->remote_bd_addr);
        printf(" Data: ");
        btutil_adv_printPacketBytes(adb_database[i].data);

        printf("\n");
    }
}

Add a new “decode” Command

The next thing to do is to add a function to print out decoded packets (or the whole table).  So I wrote this:

static void adb_printDecodePacket(int entry)
{
    int start,end;
 
    if(entry == -1)
    {
        start = 0;
        end = adb_db_count;
    }
    else
    {
        start = entry;
        end = entry;
    }

    if(end>adb_db_count)
        end = adb_db_count; 

    for(int i=start;i<=end;i++)
    {

        printf("%02d MAC: ",i);
        btutil_printBDaddress(adb_database[i].result->remote_bd_addr);
        printf("\n");
        btutil_adv_printPacketDecode(adb_database[i].data);
        printf("\n");
    }
}

After finishing that block of code, I realized I had implemented almost exactly the same functionality which two different functions.  So, I decided to redo this by doing this.  Notice that it take in a adb_print_method, in other words raw bytes or decoded packet.

typedef enum {
    ADB_PRINT_METHOD_BYTES,
    ADB_PRINT_METHOD_DECODE,
} adb_print_method_t;

static void adb_db_print(adb_print_method_t method,int entry)
{
    int start,end;
 
    if(entry < 0)
    {
        start = 0;
        end = adb_db_count;
    }
    else
    {
        start = entry;
        end = entry;
    }

    if(end>adb_db_count)
        end = adb_db_count; 

    for(int i=start;i<=end;i++)
    {
    
        printf("%02d MAC: ",i);
        btutil_printBDaddress(adb_database[i].result->remote_bd_addr);
        switch(method)
        {
        
        case ADB_PRINT_METHOD_BYTES:
            printf(" Data: ");
            btutil_adv_printPacketBytes(adb_database[i].data);
        break;

        case ADB_PRINT_METHOD_DECODE:
            printf("\n");
            btutil_adv_printPacketDecode(adb_database[i].data);
        break;
        } 
        printf("\n");
    }
}

I don’t show it here, but after changing this I had to fix up the function calls in several places in the advDatabase.

Add a new command to print decode packets

Now that I have a new method to print packets, I add a command to the database to allow the user to call it:

typedef enum {
    ADB_ADD,
    ADB_PRINT_RAW,
    ADB_PRINT_DECODE,
} adb_cmd_t;

Then in the queue loop:

switch(msg.cmd)
            {
                case ADB_ADD:
                    scan_result = (wiced_bt_ble_scan_results_t *)msg.data0;
                    data = (uint8_t *)msg.data1;
                    adb_db_add(scan_result,data);
                break;
                case ADB_PRINT_RAW:
                    adb_db_print(ADB_PRINT_METHOD_BYTES,(int)msg.data0);
                break;
                case ADB_PRINT_DECODE:
                    adb_db_print(ADB_PRINT_METHOD_DECODE,(int)msg.data0);
                break;
            }

Then the actual function

void adb_printDecode(int entry)
{
    adb_cmdMsg_t msg;
    msg.cmd = ADB_PRINT_DECODE;
    msg.data0 = (void *)entry;
    xQueueSend(adb_cmdQueue,&msg,0); // If the queue is full... oh well
}

Then add it to advDatabase.h

void adb_printDecode(int entry);

Finally to the usercmd.c

static int usrcmd_printDecode(int argc, char **argv)
{
    if(argc == 1)
    {
        adb_printDecode(-1);
    }

    if(argc == 2)
    {
        int val;
        sscanf(argv[1],"%d",&val);
        adb_printDecode(val);
    }
    return 0;
}

Program and Test

When I actually program the scanner you can see that I can print out 1 item.  OR I can decode one item.  Notice that one contains 3 fields

  • flags
  • Tx Power Level
  • Manufacturers data.  Apparently an Apple something or the other

And I can print the whole table

Or decode the whole table.

 

AnyCloud Bluetooth Advertising Scanner (Part 5)

Summary

In this article I will add a new task to the AnyCloud BLE Advertising Scanning application which will save the advertising data into a database.

Story

There is still a boatload of mostly unintelligible advertising data coming ripping onto our screen.  It is FINALLY time to start fixing that.  In this article I will create a new task called the advertising database task which will hold the history of advertising packets that I have seen.  I will update the Bluetooth Manager task to submit the advertising packets to a queue running in the advertising database task.

There are

Article Topic
AnyCloud Bluetooth Advertising Scanner (Part 1) Introduction to AnyCloud Bluetooth Advertising
AnyCloud Bluetooth Advertising Scanner (Part 2) Creating an AnyCloud Bluetooth project
AnyCloud Bluetooth Advertising Scanner (Part 3) Adding Observing functionality to the project
AnyCloud Bluetooth Utilities Library A set of APIs for enhancement of the AnyCloud Library
AnyCloud Bluetooth Advertising Scanner (Part 4) Adding a command line to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 5) Adding a history database to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 6) Decoding advertising packets
AnyCloud Bluetooth Advertising Scanner (Part 7) Adding recording commands to the command line
AnyCloud Bluetooth Advertising Scanner (Part 8) Adding filtering to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 9) Improve the print and add packet age
AnyCloud Bluetooth Advertising Scanner (Part 10) Sort the database

All of the code can be found at git@github.com:iotexpert/AnyCloudBLEScanner.git and https://github.com/iotexpert/AnyCloudBLEScanner.git

There are git tags in place starting at part 5 so that you can look at just that version of the code.  "git tag" to list the tags.  And "git checkout part6" to look at the part 6 version of the code.

You can also create a new project with this is a template if you have the IoT Expert Manifest Files installed

Create an Advertising Data Database Task

We need to create the file advertisingDatabase.h which will hold the task prototype (so that main can get going).

#pragma once

void adb_task(void *arg);

Then create the advertisingDatabase.c to hold the actual database code.  It will start with the definition of messages which can be sent to the task.  For now just “ADB_ADD”.  To make things a little bit simpler these command can have two data elements (which I call data0 and data1).  Then the main part of the task just

  1. Creates the queue to manage the messages
  2. Process the message until the end of time
#include "FreeRTOS.h"
#include "queue.h"

static QueueHandle_t adb_cmdQueue;
typedef enum {
    ADB_ADD,
} adb_cmd_t;

typedef struct
{
    adb_cmd_t cmd;
    void *data0;
    void *data1;
} adb_cmdMsg_t;

void adb_task(void *arg)
{
    // setup the queue
    adb_cmdMsg_t msg;

    adb_cmdQueue = xQueueCreate(10,sizeof(adb_cmdMsg_t));
    
    while(1)
    {
        BaseType_t status = xQueueReceive(adb_cmdQueue,&msg,portMAX_DELAY);
        if(status == pdTRUE) 
        {
            switch(msg.cmd)
            {
                case ADB_ADD:
                break;
            }

        }
    }
}

To start the task, you need to add it to main.c.

    xTaskCreate(adb_task,"adv database",configMINIMAL_STACK_SIZE*4,0,1,0);

When I build and program this, you can now see the new task.  Good that working.

AnyCloud> Unhandled Bluetooth Management Event: BTM_LOCAL_IDENTITY_KEYS_REQUEST_EVT
Started BT Stack Succesfully

AnyCloud> tasks
Name          State Priority   Stack  Num
------------------------------------------
usrcmd_ta       X       0       228     5
IDLE            R       0       115     7
Tmr Svc         B       0       223     8
CYBT_HCI_       B       5       950     3
sleep_tas       B       6       221     1
CYBT_BT_T       B       4       1371    2
blinkTask       B       0       98      4
adv datab       B       1       479     6
‘B’ – Blocked
‘R’ – Ready
‘D’ – Deleted (waiting clean up)
‘S’ – Suspended, or Blocked without a timeout
Stack = bytes free at highwater
AnyCloud>

Update the Advertising Database to Accept Submitted ADV Packets

If you recall our original setup was to take advertising packets in the Bluetooth Manager thread and print out the data.  The first thing that we want to fix up is the ability of the advertising database task to accept advertising packets which are pushed to its command queue.   To prepare for this I create two local variables to hold the data.

void adb_task(void *arg)
{
    // setup the queue
    adb_cmdMsg_t msg;
    wiced_bt_ble_scan_results_t *scan_result;
    uint8_t *data;

Then I update the ADB_ADD command.  My first, and really simple fix, is to grab the printing code from the Bluetooth Manager task.  Obviously this won’t be an improvement from the original program as far as the users goes, but it will verify that the tasks are working properly together.

                case ADB_ADD:
                    // Print the MAC Address
                    scan_result = (wiced_bt_ble_scan_results_t *)msg.data0;
                    data = (uint8_t *)msg.data1;

                    printf("MAC: ");
                    for(int i=0;i<BD_ADDR_LEN;i++)
                    {
                        printf("%02X:",scan_result->remote_bd_addr[i]);
                    }
                    // Print the RAW Data of the ADV Packet
                    printf(" Data: ");
                    int i=0;
                    while(data[i])
                    {
                        for(int j=0;j<data[i];j++)
                        {
                            printf("%02X ",data[i+1+j]);
                        }
                        i = i + data[i]+1;
                    }
                    printf("\n");
    
                    free(msg.data0);
                    free(msg.data1);
                break;

Then I add a command to the advertisingDatabase.h which the Bluetooth Manager task can call to submit advertising packets

void adb_addAdv(wiced_bt_ble_scan_results_t *scan_result,void *data);

The actual command in advertisingDatabase.c just takes the advertising information, puts it in a command message, then submits it to the command queue.

void adb_addAdv(wiced_bt_ble_scan_results_t *scan_result,void *data)
{
    adb_cmdMsg_t msg;
    msg.cmd = ADB_ADD;
    msg.data0 = (void *)scan_result;
    msg.data1 = (void *)data;
    xQueueSend(adb_cmdQueue,&msg,0); // If you loose an adv packet it is OK...
}

Update the Bluetooth Manager to Submit Adv Packets

Now I go and edit the bluetoothManager. c to submit packets rather than print them.  To do this I greatly simplify the callback.  There is one VERY important issue to deal with, which is one of those potential religious war issues.  Memory.

When you get the callback from the stack, it gives you POINTERS to data for the advertising packet that reside inside of buffers inside of the stack.  As soon as this callback returns this memory is purged.  To prevent this data from getting cleaned up by the stack I

  1. Malloc some memory for the wiced_bt_ble_scan_results
  2. Malloc some memory for the advertising data
  3. Make a copy of the data
  4. Submit it to the Advertising Database

I KNOW from the spec that the largest data packet is 31-bytes (actually it is 31-bytes + one more field with length 0).  So I know the maximum length is 32-bytes  This means that in many situations I will be copying GARBAGE into my buffer if the packet is less than 32 bytes long.  I think that this is simpler than calculating the length and then only copying that much data.

void btm_advCallback(wiced_bt_ble_scan_results_t *p_scan_result, uint8_t *p_adv_data)
{
    wiced_bt_ble_scan_results_t *scan_result = malloc(sizeof(wiced_bt_ble_scan_results_t));
    uint8_t *data = malloc(32);
   
    memcpy(data,p_adv_data,32);
    memcpy(scan_result,p_scan_result->remote_bd_addr,BD_ADDR_LEN);
    adb_addAdv(scan_result,data);
}

When I run this updated program I should get the same stream of data coming out on the serial port.  Sure enough the new thread is working.

Create an Advertising Data Database

Now, lets create an actual database.  To simplify things my database is just an array of structures.  One structure per bluetooth device.  The structure will contain a pointer to the information about the device it just saw and the actual raw data.

typedef struct {
    wiced_bt_ble_scan_results_t *result;
    uint8_t *data;
} adb_adv_t ;

#define ADB_MAX_SIZE (40)
adb_adv_t adb_database[ADB_MAX_SIZE];
int adb_db_count=0;

Then I will create several helper functions to work with the database

  1. Find devices in the database given a mac address
  2. Print an entry in the database
  3. Add entries to the database

First, find an entry in the database.  This function will search through the database and compare the mac address against the mac address in the database.  When the memcmp ==0 meaning it found a match, it will return that entry.

static int adb_db_find(wiced_bt_device_address_t *add)
{
    int rval=-1;
    for(int i=0;i<adb_db_count;i++)
    {
        if(memcmp(add,&adb_database[i].result->remote_bd_addr,BD_ADDR_LEN)==0)
        {
            rval = i;
            break;
        }
    }
    return rval;
}

The print function will make sure that you asked for a legal entry (much must be greater than 0… and less than the max).  Then it will print out the mac address and the raw data.  In a future post I will add a smarter print out.

static void adb_db_printEntry(int entry)
{
    if(!(entry>= 0 && entry <= adb_db_count))
    {
        printf("Illegal entry\n");
        return;
    }
    printf("%02d MAC: ",entry);

    for(int i=0;i<BD_ADDR_LEN;i++)
    {
        printf("%02X:",adb_database[entry].result->remote_bd_addr[i]);
    }

    // Print the RAW Data of the ADV Packet
    printf(" Data: ");
    int i=0;
    while(adb_database[entry].data[i])
    {
        for(int j=0;j<adb_database[entry].data[i];j++)
        {
            printf("%02X ",adb_database[entry].data[i+1+j]);
        }
        i = i + adb_database[entry].data[i]+1;
    }
    printf("\n");
}

To add an entry to the database, first make sure that it isn’t already in the database.  Then when you are sure that it isn’t the database, you just add the pointers to your table.  You need to make sure and not go beyond the end of the table, and if you did, you will have effectively blown away the last entry in the table.  Oh well.

static void adb_db_add(wiced_bt_ble_scan_results_t *scan_result,uint8_t *data)
{
 
    int entry = adb_db_find(&scan_result->remote_bd_addr);
    if(entry == -1)
    {
        
        adb_database[adb_db_count].result = scan_result;
        adb_database[adb_db_count].data = data;
        adb_db_printEntry(adb_db_count);
        adb_db_count = adb_db_count + 1;
        if(adb_db_count == ADB_MAX_SIZE)
        {
            printf("ADV Table Max Size\n");
            adb_db_count = adb_db_count - 1;
        }
    }
    else
    {
        free(scan_result);
        free(data);
    }
}

Add a Command to Print the Database

Now we want to add the ability to print from the command line.  So add a new command message to the list of legal commands.

typedef enum {
    ADB_ADD,
    ADB_PRINT,
} adb_cmd_t;

Then create a new function to print.  If you send in a “-1” it will print the whole table.  Otherwise just print the individual entry.

static void adb_printTable(int entry)
{
    if(entry == -1)
    {
        for(int i=0;i<adb_db_count;i++)
        {
            adb_db_printEntry(i);
        }

    }
    else
    {
        adb_db_printEntry(entry);
    }
    

}

Now edit usercmd.c to have the new command line.  Notice that I use “sscanf” which obviously has some issues.  Too bad.

static int usrcmd_print(int argc, char **argv)
{

    if(argc == 1)
    {
        adb_print(-1); // Print whole table
    }

    if(argc == 2)
    {
        int val;
        sscanf(argv[1],"%d",&val);
        adb_print(val);
    }

    return 0;
}

When I program the project it immediately prints out a bunch of devices that are at my house.  Then you can see I run the “print” command which prints the table.  Finally P do a print 0 to just print the first entry.

In the next article I will add smarter diagnostics to the advertising packets.

AnyCloud Bluetooth Utilities Library

Summary

This article is a discussion of a library of utilities functions that support AnyCloud Bluetooth development.  It includes settings to configure the hardware, functions to decode stack events, functions to decode advertising packets etc.

Story

The Cypress, now Infineon, Modus Toolbox team has been working to bring the WICED Bluetooth devices to be closer and more compatible with the PSoC 6 tools.  One of the important enablement things we have done is turn on the WICED Bluetooth Host stack on the PSoC 6 so that it can effectively talk to the CYW43XXX Bluetooth / WiFi combo chips.

As I have been using all of the new stuff I found myself adding my own custom functionality…. and after a while I realized (finally) that I should put all of those little helper things into a library, specifically an IoT Expert library.  For now this library contains:

  • The Bluetooth Platform Configuration Settings
  • Functions to decode stack events
  • Functions to decode advertising packets

but imagine with time I will add more functions and templates.

bt_platform_cfg_settings

As I discussed in the article AnyCloud Bluetooth Advertising Scanner (Part 1), every single AnyCloud BLE Stack project will require a structure of type wiced_bt_cfg_settings_t.  This structure is used to setup the hardware before getting the stack going.  Remember you need to make a call like this to initialize the Bluetooth hardware.

    cybt_platform_config_init(&bt_platform_cfg_settings);

At some point this file will be included automatically for you by the Modus Toolbox team, but for now I have added this to my library.  This file look like this.  Basically a bunch of pin definitions which are set for you automatically by the BSP.  Obviously you can make your own, but this should work on all of the Cypress development kits (I think)

#include "cybt_platform_config.h"
#include "cybsp.h"
#include "wiced_bt_stack.h"

const cybt_platform_config_t bt_platform_cfg_settings =
{
    .hci_config =
    {
        .hci_transport = CYBT_HCI_UART,

        .hci =
        {
            .hci_uart =
            {
                .uart_tx_pin = CYBSP_BT_UART_TX,
                .uart_rx_pin = CYBSP_BT_UART_RX,
                .uart_rts_pin = CYBSP_BT_UART_RTS,
                .uart_cts_pin = CYBSP_BT_UART_CTS,

                .baud_rate_for_fw_download = 115200,
                .baud_rate_for_feature     = 115200,

                .data_bits = 8,
                .stop_bits = 1,
                .parity = CYHAL_UART_PARITY_NONE,
                .flow_control = WICED_TRUE
            }
        }
    },

    .controller_config =
    {
        .bt_power_pin      = CYBSP_BT_POWER,
        .sleep_mode =
        {
            #if (bt_0_power_0_ENABLED == 1) /* BT Power control is enabled in the LPA */
            #if (CYCFG_BT_LP_ENABLED == 1) /* Low power is enabled in the LPA, use the LPA configuration */
            .sleep_mode_enabled = true,
            .device_wakeup_pin = CYCFG_BT_DEV_WAKE_GPIO,
            .host_wakeup_pin = CYCFG_BT_HOST_WAKE_GPIO,
            .device_wake_polarity = CYCFG_BT_DEV_WAKE_POLARITY,
            .host_wake_polarity = CYCFG_BT_HOST_WAKE_IRQ_EVENT
            #else /* Low power is disabled in the LPA, disable low power */
            .sleep_mode_enabled = false
            #endif
            #else /* BT Power control is disabled in the LPA – default to BSP low power configuration */
            .sleep_mode_enabled = true,
            .device_wakeup_pin = CYBSP_BT_DEVICE_WAKE,
            .host_wakeup_pin = CYBSP_BT_HOST_WAKE,
            .device_wake_polarity = CYBT_WAKE_ACTIVE_LOW,
            .host_wake_polarity = CYBT_WAKE_ACTIVE_LOW
            #endif
        }
    },

    .task_mem_pool_size    = 2048
};

btutil_stack

When you startup the Bluetooth Host stack you are responsible for providing a “management callback” which has the function prototype

typedef wiced_result_t (wiced_bt_management_cback_t) (wiced_bt_management_evt_t event, wiced_bt_management_evt_data_t *p_event_data);

The first parameter is an “event” which is  just an enumerated list of possible events by the Bluetooth Host Stack.  Here is the actual list.

enum wiced_bt_management_evt_e {
    /* Bluetooth status events */
    BTM_ENABLED_EVT,                                /**< Bluetooth controller and host stack enabled. Event data: wiced_bt_dev_enabled_t */
    BTM_DISABLED_EVT,                               /**< Bluetooth controller and host stack disabled. Event data: NULL */
    BTM_POWER_MANAGEMENT_STATUS_EVT,                /**< Power management status change. Event data: wiced_bt_power_mgmt_notification_t */
    BTM_RE_START_EVT,                               /**< Bluetooth controller and host stack re-enabled. Event data: tBTM_ENABLED_EVT */
    /* Security events */
    BTM_PIN_REQUEST_EVT,                            /**< PIN request (used only with legacy devices). Event data: #wiced_bt_dev_name_and_class_t */
    BTM_USER_CONFIRMATION_REQUEST_EVT,              /**< received USER_CONFIRMATION_REQUEST event (respond using #wiced_bt_dev_confirm_req_reply). Event data: #wiced_bt_dev_user_cfm_req_t */
    BTM_PASSKEY_NOTIFICATION_EVT,                   /**< received USER_PASSKEY_NOTIFY event. Event data: #wiced_bt_dev_user_key_notif_t */
    BTM_PASSKEY_REQUEST_EVT,                        /**< received USER_PASSKEY_REQUEST event @cond DUAL_MODE (respond using #wiced_bt_dev_pass_key_req_reply). Event data: #wiced_bt_dev_user_key_req_t @endcond
                                                     @note  BR/EDR Only */
    BTM_KEYPRESS_NOTIFICATION_EVT,                  /**< received KEYPRESS_NOTIFY event. Event data: #wiced_bt_dev_user_keypress_t */
    BTM_PAIRING_IO_CAPABILITIES_BR_EDR_REQUEST_EVT, /**< Requesting IO capabilities for BR/EDR pairing. Event data: #wiced_bt_dev_bredr_io_caps_req_t 
                                                        @note  BR/EDR Only */
    BTM_PAIRING_IO_CAPABILITIES_BR_EDR_RESPONSE_EVT,/**< Received IO capabilities response for BR/EDR pairing. Event data: @cond DUAL_MODE #wiced_bt_dev_bredr_io_caps_rsp_t @endcond
                                                        @note  BR/EDR Only*/
    BTM_PAIRING_IO_CAPABILITIES_BLE_REQUEST_EVT,    /**< Requesting IO capabilities for BLE pairing. Slave can check peer io capabilities in event data before updating with local io capabilities. Event data: #wiced_bt_dev_ble_io_caps_req_t */
    BTM_PAIRING_COMPLETE_EVT,                       /**< received SIMPLE_PAIRING_COMPLETE event. Event data: #wiced_bt_dev_pairing_cplt_t */
    BTM_ENCRYPTION_STATUS_EVT,                      /**< Encryption status change. Event data: #wiced_bt_dev_encryption_status_t */
    BTM_SECURITY_REQUEST_EVT,                       /**< Security request (respond using #wiced_bt_ble_security_grant). Event data: #wiced_bt_dev_security_request_t */
    BTM_SECURITY_FAILED_EVT,                        /**< Security procedure/authentication failed. Event data: #wiced_bt_dev_security_failed_t */
    BTM_SECURITY_ABORTED_EVT,                       /**< Security procedure aborted locally, or unexpected link drop. Event data: #wiced_bt_dev_name_and_class_t */

    BTM_READ_LOCAL_OOB_DATA_COMPLETE_EVT,           /**< Result of reading local OOB data @cond DUAL_MODE (#wiced_bt_dev_read_local_oob_data). Event data: #wiced_bt_dev_local_oob_t @endcond 
                                                        @note  BR/EDR Only */

    BTM_REMOTE_OOB_DATA_REQUEST_EVT,                /**< OOB data from remote device @cond DUAL_MODE (respond using #wiced_bt_dev_remote_oob_data_reply). Event data: #wiced_bt_dev_remote_oob_t @endcond 
                                                        @note  BR/EDR Only */

    BTM_PAIRED_DEVICE_LINK_KEYS_UPDATE_EVT,         /**< Updated remote device link keys (store device_link_keys to  NV memory). This is the place to
verify that the correct link key has been generated. Event data: #wiced_bt_device_link_keys_t */
    BTM_PAIRED_DEVICE_LINK_KEYS_REQUEST_EVT,        /**< Request for stored remote device link keys (restore device_link_keys from NV memory). If successful, return WICED_BT_SUCCESS. Event data: #wiced_bt_device_link_keys_t */

    BTM_LOCAL_IDENTITY_KEYS_UPDATE_EVT,             /**< Update local identity key (stored local_identity_keys NV memory). Event data: #wiced_bt_local_identity_keys_t */
    BTM_LOCAL_IDENTITY_KEYS_REQUEST_EVT,            /**< Request local identity key (get local_identity_keys from NV memory). If successful, return WICED_BT_SUCCESS. Event data: #wiced_bt_local_identity_keys_t */

    BTM_BLE_SCAN_STATE_CHANGED_EVT,                 /**< BLE scan state change. Event data: #wiced_bt_ble_scan_type_t */
    BTM_BLE_ADVERT_STATE_CHANGED_EVT,               /**< BLE advertisement state change. Event data: #wiced_bt_ble_advert_mode_t */

    /* BLE Secure Connection events */
    BTM_SMP_REMOTE_OOB_DATA_REQUEST_EVT,            /**< SMP remote oob data request. Reply using wiced_bt_smp_oob_data_reply. Event data: #wiced_bt_smp_remote_oob_req_t  */
    BTM_SMP_SC_REMOTE_OOB_DATA_REQUEST_EVT,         /**< LE secure connection remote oob data request. Reply using wiced_bt_smp_sc_oob_reply. Event data: #wiced_bt_smp_sc_remote_oob_req_t 
                                                        @note  BR/EDR Only */
    BTM_SMP_SC_LOCAL_OOB_DATA_NOTIFICATION_EVT,     /**< LE secure connection local OOB data (wiced_bt_smp_create_local_sc_oob_data). Event data: #wiced_bt_smp_sc_local_oob_t */

    BTM_SCO_CONNECTED_EVT,                          /**< SCO connected event. Event data: @cond DUAL_MODE #wiced_bt_sco_connected_t @endcond
                                                        @note  BR/EDR Only */
    BTM_SCO_DISCONNECTED_EVT,                       /**< SCO disconnected event. Event data: @cond #wiced_bt_sco_disconnected_t @endcond
                                                        @note  BR/EDR Only */
    BTM_SCO_CONNECTION_REQUEST_EVT,                 /**< SCO connection request event. Event data: @cond #wiced_bt_sco_connection_request_t @endcond
                                                        @note  BR/EDR Only */
    BTM_SCO_CONNECTION_CHANGE_EVT,                  /**< SCO connection change event. Event data: @cond #wiced_bt_sco_connection_change_t @endcond
                                                        @note  BR/EDR Only */
    BTM_BLE_CONNECTION_PARAM_UPDATE,                /**< BLE connection parameter update. Event data: #wiced_bt_ble_connection_param_update_t */
    BTM_BLE_PHY_UPDATE_EVT,                         /**< BLE Physical link update. Event data: wiced_bt_ble_phy_update_t */
    BTM_LPM_STATE_LOW_POWER,                        /**< BT device wake has been deasserted. Used for Host Stack Use Case. */
    BTM_MULTI_ADVERT_RESP_EVENT,                    /**< Multi adv command status event Used for the status of the command sent */
#if SMP_CATB_CONFORMANCE_TESTER == TRUE
    BTM_SMP_SC_PEER_INFO_EVT                        /** The Secure Connections support information of the peer device */
#endif

};

While you are trying to figure out what is going on during the development, it is very useful to be able to print out the name of the events (instead of the numbers).  In other words instead of doing

printf("Event = %02X\n",event);

it is way better to do

printf("Event Name=%s\n",btutil_getBTEventName(event));

While I was looking at an example project I found this function which I thought was awesome.

const char *btutil_getBTEventName(wiced_bt_management_evt_t event)
{
    switch ( (int)event )
    {
    CASE_RETURN_STR(BTM_ENABLED_EVT)
    CASE_RETURN_STR(BTM_DISABLED_EVT)
    CASE_RETURN_STR(BTM_POWER_MANAGEMENT_STATUS_EVT)
    CASE_RETURN_STR(BTM_PIN_REQUEST_EVT)
    CASE_RETURN_STR(BTM_USER_CONFIRMATION_REQUEST_EVT)
    CASE_RETURN_STR(BTM_PASSKEY_NOTIFICATION_EVT)
    CASE_RETURN_STR(BTM_PASSKEY_REQUEST_EVT)
    CASE_RETURN_STR(BTM_KEYPRESS_NOTIFICATION_EVT)
    CASE_RETURN_STR(BTM_PAIRING_IO_CAPABILITIES_BR_EDR_REQUEST_EVT)
    CASE_RETURN_STR(BTM_PAIRING_IO_CAPABILITIES_BR_EDR_RESPONSE_EVT)
    CASE_RETURN_STR(BTM_PAIRING_IO_CAPABILITIES_BLE_REQUEST_EVT)
    CASE_RETURN_STR(BTM_PAIRING_COMPLETE_EVT)
    CASE_RETURN_STR(BTM_ENCRYPTION_STATUS_EVT)
    CASE_RETURN_STR(BTM_SECURITY_REQUEST_EVT)
    CASE_RETURN_STR(BTM_SECURITY_FAILED_EVT)
    CASE_RETURN_STR(BTM_SECURITY_ABORTED_EVT)
    CASE_RETURN_STR(BTM_READ_LOCAL_OOB_DATA_COMPLETE_EVT)
    CASE_RETURN_STR(BTM_REMOTE_OOB_DATA_REQUEST_EVT)
    CASE_RETURN_STR(BTM_PAIRED_DEVICE_LINK_KEYS_UPDATE_EVT)
    CASE_RETURN_STR(BTM_PAIRED_DEVICE_LINK_KEYS_REQUEST_EVT)
    CASE_RETURN_STR(BTM_LOCAL_IDENTITY_KEYS_UPDATE_EVT)
    CASE_RETURN_STR(BTM_LOCAL_IDENTITY_KEYS_REQUEST_EVT)
    CASE_RETURN_STR(BTM_BLE_SCAN_STATE_CHANGED_EVT)
    CASE_RETURN_STR(BTM_BLE_ADVERT_STATE_CHANGED_EVT)
    CASE_RETURN_STR(BTM_SMP_REMOTE_OOB_DATA_REQUEST_EVT)
    CASE_RETURN_STR(BTM_SMP_SC_REMOTE_OOB_DATA_REQUEST_EVT)
    CASE_RETURN_STR(BTM_SMP_SC_LOCAL_OOB_DATA_NOTIFICATION_EVT)
    CASE_RETURN_STR(BTM_SCO_CONNECTED_EVT)
    CASE_RETURN_STR(BTM_SCO_DISCONNECTED_EVT)
    CASE_RETURN_STR(BTM_SCO_CONNECTION_REQUEST_EVT)
    CASE_RETURN_STR(BTM_SCO_CONNECTION_CHANGE_EVT)
    CASE_RETURN_STR(BTM_BLE_CONNECTION_PARAM_UPDATE)
#ifdef CYW20819A1
    CASE_RETURN_STR(BTM_BLE_PHY_UPDATE_EVT)
#endif
    }

    return NULL;
}

And then I learned something new when I looked at the “function” CASE_RETURN_STR which used compiler trick to turn an enumerated value into a string.

#define CASE_RETURN_STR(enum_val)          case enum_val: return #enum_val;

This allows you to do this in your management callback (notice line 16 where the string is printed out)

wiced_result_t app_bt_management_callback(wiced_bt_management_evt_t event, wiced_bt_management_evt_data_t *p_event_data)
{
    wiced_result_t result = WICED_BT_SUCCESS;

    switch (event)
    {
        case BTM_ENABLED_EVT:
            if (WICED_BT_SUCCESS == p_event_data->enabled.status)
            {
                printf("Started BT Stack Succesfully\n");
                wiced_bt_ble_observe(WICED_TRUE,0,obv_callback);
            }
            break;

        default:
            printf("Unhandled Bluetooth Management Event: %s\n", btutil_getBTEventName(event));
            break;
    }

    return result;
}

It turns out that there are several other places where the stack gives you an event-ish thing.  So these functions were created as well

#pragma once

const char *btutil_getBTEventName(wiced_bt_management_evt_t event);
const char *btutil_getBLEAdvertModeName(wiced_bt_ble_advert_mode_t mode);
const char *btutil_getBLEGattDisconnReasonName(wiced_bt_gatt_disconn_reason_t reason);
const char *btutil_getBLEGattStatusName(wiced_bt_gatt_status_t status);

btutil_adv_decode

In AnyCloud Bluetooth Advertising Scanner (Part 3) I discussed the format of the advertising packet.  So I created functions which will decode the data in the advertising packets.  More on the future article AnyCloud Bluetooth Advertising Scanner (Part 4 or maybe 5 or maybe 6).  Here are the functions:

#pragma once

wiced_bool_t btutil_isEddystone(uint8_t *data);
wiced_bool_t btutil_is_iBeacon(uint8_t *data);
wiced_bool_t btutil_isCypress(uint8_t *data);

int btutil_adv_len(uint8_t *packet);
void btutil_adv_printPacketDecode(uint8_t *packet);
void btutil_adv_printPacketBytes(uint8_t *packet);

btutil

And because I like to have just one include to get access to all of the function I created “btutil.h” which just includes all of the headers in one place.

#pragma once

#include "btutil_adv_decode.h"
#include "btutil_stack.h"
#include "btutil_general.h"
#include "bt_platform_cfg_settings.h"

Add to the IoT Expert Manifest

In order to set it up for my library to live in the library manager I updated the IoT Expert Manifest file to have a link to the GitHub repository

<middleware>
  
    <name>Bluetooth Utilities</name>
    <id>btutil</id>
    <uri>https://github.com/iotexpert/btutil</uri>
    <desc>A library of Bluetooth Debugging Utilties for Cypress PSoC6 Anycloud</desc>
    <category>IoT Expert</category>
    <req_capabilities>psoc6</req_capabilities>
    <versions>
      <version flow_version="1.0,2.0">
        <num>master</num>
        <commit>master</commit>
        <desc>master</desc>
      </version>
    </versions>
  </middleware>

And now the library manager has the IoT Expert Bluetooth Utilities.

 

 

AnyCloud Bluetooth Advertising Scanner (Part 1)

Summary

The first of several articles discussing the use of the AnyCloud BLE Stack to build advertising scanner/observers.

Story

A few summers ago while I was writing the WICED Bluetooth Academy book, I created a WICED based BLE advertising scanner.  Actually, I created a framework for the scanner and the remarkable summer intern I had finished the work.  That project has been sitting in the source code repository for the Bluetooth class, mostly only shown to face-to-face students.  This scanner is built using some of the original code combined with the new AnyCloud Bluetooth SDK.  It will act sort-of-like LightBlue or one of the other Bluetooth advertising scanners you might run on your phone, but with a serial console.

Sometime in the last few months we released the Bluetooth SDK for AnyCloud (things have been crazy and I have lost track of time)  This SDK has all of the stuff needed to add Bluetooth to your AnyCloud project using one of the Cypress Bluetooth/WiFi combo chips.  I had not had a chance to try it out, so I decided to build a Bluetooth project and then port the scanning code.

There are

Article Topic
AnyCloud Bluetooth Advertising Scanner (Part 1) Introduction to AnyCloud Bluetooth Advertising
AnyCloud Bluetooth Advertising Scanner (Part 2) Creating an AnyCloud Bluetooth project
AnyCloud Bluetooth Advertising Scanner (Part 3) Adding Observing functionality to the project
AnyCloud Bluetooth Utilities Library A set of APIs for enhancement of the AnyCloud Library
AnyCloud Bluetooth Advertising Scanner (Part 4) Adding a command line to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 5) Adding a history database to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 6) Decoding advertising packets
AnyCloud Bluetooth Advertising Scanner (Part 7) Adding recording commands to the command line
AnyCloud Bluetooth Advertising Scanner (Part 8) Adding filtering to the scanner
AnyCloud Bluetooth Advertising Scanner (Part 9) Improve the print and add packet age
AnyCloud Bluetooth Advertising Scanner (Part 10) Sort the database

All of the code can be found at git@github.com:iotexpert/AnyCloudBLEScanner.git and https://github.com/iotexpert/AnyCloudBLEScanner.git

There are git tags in place starting at part 5 so that you can look at just that version of the code.  "git tag" to list the tags.  And "git checkout part6" to look at the part 6 version of the code.

You can also create a new project with this is a template if you have the IoT Expert Manifest Files installed

Bluetooth Application Architecture

Bluetooth applications are divided into these four pieces

  1. You user application which responds to events and sends messages from/to the Bluetooth host stack
  2. A Bluetooth Host Stack
  3. A Bluetooth Controller Stack
  4. The Bluetooth Radio

These four pieces can be divided into multiple chips, as few as one or as many as four.  However, for this article, the project will be built to run on a PSoC 6 + CYW43012 WiFi/Bluetooth Combo chip.  Specifically:

  1. My scanner application running on the PSoC 6
  2. The Bluetooth Host Stack running on the PSoC 6
  3. The BlueTooth Controller Firmware running on the CYW43012
  4. A Bluetooth Radio on the CYW43012

But how do they talk?  Simple, there is:

  1. A UART Host Controller Interface (HCI) between the two chips
  2. A GPIO to serve as a deep sleep wakeup from the 43012 –> PSoC 6
  3. A GPIO to serve as the bluetooth controller wakeup from the PSoC 6 –> 43012
  4. A GPIO to turn on the Bluetooth regulator from the PSoC 6 –> 43012

Here is the block diagram from the CY8CKIT-062S2-43012 Kit Guide.  Notice that signals labeled UART and Control going between the PSoC 6 and the CYW43012.

And when you read more deeply into the schematic you can see the signals labeled

  • BT_UART_TXD/RXD/CTS/RTS
  • BT_HOST_WAKE
  • BT_DEV_WAKE
  • BT_REG_ON

How to Start the AnyCloud Bluetooth Stack

To actually start the AnyCloud Bluetooth stack you will call two functions

  1. cybt_platform_config_init – that will setup the hardware interface to the CYW43012
  2. wiced_bt_stack_init that will:
    1. Start a task to manage the Host Controller Interface
    2. Download the controller firmware to the CYW43012
    3. Start a task to manage the host stack
    4. Initialize both the host and the controller
    5. Call you back when that is all done

Here is an example from main.

    cybt_platform_config_init(&bt_platform_cfg_settings);
    wiced_bt_stack_init (app_bt_management_callback, &wiced_bt_cfg_settings);

When you look at these two function calls, you will find that you need to provide three things:

  1. A platform hardware configuration structure called bt_platform_cfg_settings
  2. The Bluetooth stack configuration settings structure called wiced_bt_cfg_settings
  3. A management callback called app_bt_management_callback

bt_platform_cfg_settings

The purpose of the hardware configuration structure is to define the UART + parameters and the wakeup GPIOs.  Specifically, the hardware configuration structure defines the configuration of the host controller interface (hci)

  1. The HCI transport scheme (in this case UART)
  2. The pins of the UART
  3. Baud Rate
  4. Data Bits
  5. Stop Bits
  6. Parity
  7. Flow Control

And the controller low power behavior (in the .controller_config member)

This is a fairly standard configuration and I think that we should help you by providing this structure somewhere in the BSP.  But for now, you need to provide it (in an upcoming article I’ll update the IoT Expert Bluetooth Library to provide it).  Here is the specific structure that I will be using.

const cybt_platform_config_t bt_platform_cfg_settings =
{
    .hci_config =
    {
        .hci_transport = CYBT_HCI_UART,

        .hci =
        {
            .hci_uart =
            {
                .uart_tx_pin = CYBSP_BT_UART_TX,
                .uart_rx_pin = CYBSP_BT_UART_RX,
                .uart_rts_pin = CYBSP_BT_UART_RTS,
                .uart_cts_pin = CYBSP_BT_UART_CTS,

                .baud_rate_for_fw_download = 115200,
                .baud_rate_for_feature     = 115200,

                .data_bits = 8,
                .stop_bits = 1,
                .parity = CYHAL_UART_PARITY_NONE,
                .flow_control = WICED_TRUE
            }
        }
    },

    .controller_config =
    {
        .bt_power_pin      = CYBSP_BT_POWER,
        .sleep_mode =
        {
            #if (bt_0_power_0_ENABLED == 1) /* BT Power control is enabled in the LPA */
            #if (CYCFG_BT_LP_ENABLED == 1) /* Low power is enabled in the LPA, use the LPA configuration */
            .sleep_mode_enabled = true,
            .device_wakeup_pin = CYCFG_BT_DEV_WAKE_GPIO,
            .host_wakeup_pin = CYCFG_BT_HOST_WAKE_GPIO,
            .device_wake_polarity = CYCFG_BT_DEV_WAKE_POLARITY,
            .host_wake_polarity = CYCFG_BT_HOST_WAKE_IRQ_EVENT
            #else /* Low power is disabled in the LPA, disable low power */
            .sleep_mode_enabled = false
            #endif
            #else /* BT Power control is disabled in the LPA – default to BSP low power configuration */
            .sleep_mode_enabled = true,
            .device_wakeup_pin = CYBSP_BT_DEVICE_WAKE,
            .host_wakeup_pin = CYBSP_BT_HOST_WAKE,
            .device_wake_polarity = CYBT_WAKE_ACTIVE_LOW,
            .host_wake_polarity = CYBT_WAKE_ACTIVE_LOW
            #endif
        }
    },

    .task_mem_pool_size    = 2048
};

wiced_bt_cfg_settings

The Cypress WICED Bluetooth Stack has a boatload of configuration settings.  When you call the stack start function you need to provide all of those settings in a structure of type “wiced_bt_cfg_settings_t” which is actually a structure of structures.  There are several basic ways to set these settings

  • Start from scratch and build you own settings
  • Copy from an example project
  • Use the Bluetooth Configurator to generate the structure

For the purposes of THIS project I started by copying the structure from on of the example projects and then modifying the three numbers that were relevant to me.  Specifically

  • max_simultanous_link – which I changed to 0 because this is simply a Bluetooth Observer
  • low_duty_scan_interval – how long in the window to listen for advertising packets
  • low_duty_scan_window – how wide the window of listening should be
const wiced_bt_cfg_settings_t wiced_bt_cfg_settings =
{
    .device_name                         = (uint8_t *)BT_LOCAL_NAME,                                   /**< Local device name (NULL terminated) */
    .device_class                        = {0x00, 0x00, 0x00},                                         /**< Local device class */
    .security_requirement_mask           = BTM_SEC_NONE,                                               /**< Security requirements mask (BTM_SEC_NONE, or combinination of BTM_SEC_IN_AUTHENTICATE, BTM_SEC_OUT_AUTHENTICATE, BTM_SEC_ENCRYPT (see #wiced_bt_sec_level_e)) */

    .max_simultaneous_links              = 0,                                                          /**< Maximum number simultaneous links to different devices */

    .ble_scan_cfg =                                                 /* BLE scan settings  */
    {
        .scan_mode                       = BTM_BLE_SCAN_MODE_PASSIVE,                                  /**< BLE scan mode (BTM_BLE_SCAN_MODE_PASSIVE, BTM_BLE_SCAN_MODE_ACTIVE, or BTM_BLE_SCAN_MODE_NONE) */

        /* Advertisement scan configuration */
        .high_duty_scan_interval         = WICED_BT_CFG_DEFAULT_HIGH_DUTY_SCAN_INTERVAL,               /**< High duty scan interval */
        .high_duty_scan_window           = WICED_BT_CFG_DEFAULT_HIGH_DUTY_SCAN_WINDOW,                 /**< High duty scan window */
        .high_duty_scan_duration         = 0,                                                          /**< High duty scan duration in seconds (0 for infinite) */

        .low_duty_scan_interval          = 96,                                                         /**< Low duty scan interval  */
        .low_duty_scan_window            = 96,                                                         /**< Low duty scan window */
        .low_duty_scan_duration          = 0,                                                          /**< Low duty scan duration in seconds (0 for infinite) */

        /* Connection scan configuration */
        .high_duty_conn_scan_interval    = WICED_BT_CFG_DEFAULT_HIGH_DUTY_CONN_SCAN_INTERVAL,          /**< High duty cycle connection scan interval */
        .high_duty_conn_scan_window      = WICED_BT_CFG_DEFAULT_HIGH_DUTY_CONN_SCAN_WINDOW,            /**< High duty cycle connection scan window */
        .high_duty_conn_duration         = 0,                                                         /**< High duty cycle connection duration in seconds (0 for infinite) */

        .low_duty_conn_scan_interval     = WICED_BT_CFG_DEFAULT_LOW_DUTY_CONN_SCAN_INTERVAL,           /**< Low duty cycle connection scan interval */
        .low_duty_conn_scan_window       = WICED_BT_CFG_DEFAULT_LOW_DUTY_CONN_SCAN_WINDOW,             /**< Low duty cycle connection scan window */
        .low_duty_conn_duration          = 0,                                                         /**< Low duty cycle connection duration in seconds (0 for infinite) */

        /* Connection configuration */
        .conn_min_interval               = WICED_BT_CFG_DEFAULT_CONN_MIN_INTERVAL,                     /**< Minimum connection interval */
        .conn_max_interval               = WICED_BT_CFG_DEFAULT_CONN_MAX_INTERVAL,                     /**< Maximum connection interval */
        .conn_latency                    = WICED_BT_CFG_DEFAULT_CONN_LATENCY,                          /**< Connection latency */
        .conn_supervision_timeout        = WICED_BT_CFG_DEFAULT_CONN_SUPERVISION_TIMEOUT,              /**< Connection link supervision timeout */
    },

    .default_ble_power_level            = 12                                                           /**< Default LE power level, Refer lm_TxPwrTable table for the power range */
};

app_bt_management_callback

The last thing that you need to provide is a management callback.  This function is called by the Bluetooth Stack when a “management event” occurs.  There is a big-long-list of enumerated events of type wiced_bt_management_event_t.  The events include things like the the stack started “BTM_ENABLED_EVENT”.  Each event may have data associated with the event which is passed to you in a pointer to wiced_bt_management_event_data_t.

You typically deal with these events with a giant switch statement like this:

wiced_result_t app_bt_management_callback(wiced_bt_management_evt_t event, wiced_bt_management_evt_data_t *p_event_data)
{
    wiced_result_t result = WICED_BT_SUCCESS;

    switch (event)
    {
        case BTM_ENABLED_EVT:

            if (WICED_BT_SUCCESS == p_event_data->enabled.status)
            {
               printf("Stack Started Successfully\n");
            }

            break;


        default:
            printf("Unhandled Bluetooth Management Event: 0x%x %s\n", event, btutil_getBTEventName(event));
            break;
    }

    return result;
}

Tasks

The Bluetooth stack on the PSoC6 is operated with two tasks.  Specifically, when you call the wiced_bt_stack_init it will startup:

  1. CYBT_HCI_Task – a task that sends and receives HCI packets going to the Radio chip
  2. CY_BT_Task – a task that manages the Bluetooth Host Stack

Here is print of the task list from my project:

AnyCloud> tasks
Name          State Priority   Stack  Num
------------------------------------------
nt shell        X       0       236     5
IDLE            R       0       115     6
blink           B       0       98      4
CYBT_BT_Task    B       4       1371    2
sleep_task      B       6       217     1
CYBT_HCI_Task   B       5       950     3
Tmr Svc         B       6       76      7
‘B’ – Blocked
‘R’ – Ready
‘D’ – Deleted (waiting clean up)
‘S’ – Suspended, or Blocked without a timeout
Stack = bytes free at highwater

 

Now with the background in place, in the next article I will discuss Bluetooth advertising and how to build the observer project.

ModusToolbox 2.2 Template Project – FreeRTOS + NTShell

Summary

This article discusses the new library structure that was released with ModusToolbox 2.2.  I explain it by showing the creation of a template project that use FreeRTOS and NT Shell.

Story

I have often started projects from the IoT Expert FreeRTOS template project.   I realized the other day that almost always the first thing I do after creating the project is add the NT Shell library.  My friend Hassane has a personal mantra that if he is going to do the same job more than once he will always automate it.  I should have listened to him on this one because I have done it a bunch of times.

In Modus Toolbox 2.2 we have created a new library scheme which allows sharing of libraries between projects.  So this will also be a good example of how that works.

This will also give you another example of adding template projects to your own manifest.

Here is what I am going to do:

  1. Create a project from the IoT Expert FreeRTOS Template
  2. Add the NTShell Library & Examine New Library Structure
  3. Update the Project and Program
  4. Add the Task List functionality (a nice feature of FreeRTOS)
  5. Put the new template on GitHub
  6. Update the IoT Expert App Manifest
  7. Test the new Template

Create & Test a project from the IoT Expert FreeRTOS Template

I will start the whole process by creating  new project using my existing base template.  The kit that I happen to have on my desk right now is the CY8CKIT-062S2-43012.

Select the IoT Expert FreeRTOS Template and give it a name.  Notice that I add “NTShell” to the name (because that is what Im gonna add)

When you click create, Modus will do its magic and build you a complete project.

Today Im going to edit using Visual Studio Code.  Actually almost always I edit using Visual Studio Code.  You can do all of these tasks using Eclipse as well.  To turn my created project into a VSCODE project run “make vscode”

Before getting to far down the road I like to run a build to make sure everything is OK.  So “make -j build”

arh (master) IoT_Expert_FreeRTOS_NTShell_Template $ make -j build
Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Prebuild operations complete
Commencing build operations...

Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Initializing build: MTBShellTemplate Debug CY8CKIT-062S2-43012 GCC_ARM

Auto-discovery in progress...
-> Found 195 .c file(s)
-> Found 46 .S file(s)
-> Found 23 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 6 .a file(s)
-> Found 491 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete

Constructing build rules...
Build rules construction complete

==============================================================================
= Building application =
==============================================================================
Generating compilation database file...
-> ./build/compile_commands.json
Compilation database file generation complete
Building 183 file(s)
    Compiling app file lowPower.c
    Compiling app file main.c
    Compiling ext file startup_psoc6_02_cm4.S
    Compiling ext file cy_syslib_gcc.S
    Compiling ext file cycfg.c
    Compiling ext file cycfg_capsense.c
    Compiling ext file cycfg_clocks.c

....a bunch of stuff deleted

    Compiling ext file psoc6_04_cm0p_sleep.c
    Compiling ext file cy_retarget_io.c
    Linking output file MTBShellTemplate.elf
==============================================================================
= Build complete =
==============================================================================

Calculating memory consumption: CY8C624ABZI-S2D44 GCC_ARM -Og

   ---------------------------------------------------- 
  | Section Name         |  Address      |  Size       | 
   ---------------------------------------------------- 
  | .cy_m0p_image        |  0x10000000   |  6044       | 
  | .text                |  0x10002000   |  30280      | 
  | .ARM.exidx           |  0x10009648   |  8          | 
  | .copy.table          |  0x10009650   |  24         | 
  | .zero.table          |  0x10009668   |  8          | 
  | .data                |  0x080022e0   |  1320       | 
  | .cy_sharedmem        |  0x08002808   |  8          | 
  | .noinit              |  0x08002810   |  148        | 
  | .bss                 |  0x080028a4   |  1324       | 
  | .heap                |  0x08002dd0   |  1030704    | 
   ---------------------------------------------------- 

  Total Internal Flash (Available)          2097152    
  Total Internal Flash (Utilized)           39848      

  Total Internal SRAM (Available)           1046528    
  Total Internal SRAM (Utilized with heap)  1033504    

  
arh (master) IoT_Expert_FreeRTOS_NTShell_Template $

Then program it, just to make sure.  “make program”

arh (master) IoT_Expert_FreeRTOS_NTShell_Template $ make program
Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Prebuild operations complete
Commencing build operations...

Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Initializing build: MTBShellTemplate Debug CY8CKIT-062S2-43012 GCC_ARM

Auto-discovery in progress...
-> Found 195 .c file(s)
-> Found 46 .S file(s)
-> Found 23 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 6 .a file(s)
-> Found 491 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete

Constructing build rules...
Build rules construction complete

==============================================================================
= Building application =
==============================================================================
Generating compilation database file...
-> ./build/compile_commands.json
Compilation database file generation complete
Building 183 file(s)
==============================================================================
= Build complete =
==============================================================================

Calculating memory consumption: CY8C624ABZI-S2D44 GCC_ARM -Og

   ---------------------------------------------------- 
  | Section Name         |  Address      |  Size       | 
   ---------------------------------------------------- 
  | .cy_m0p_image        |  0x10000000   |  6044       | 
  | .text                |  0x10002000   |  30280      | 
  | .ARM.exidx           |  0x10009648   |  8          | 
  | .copy.table          |  0x10009650   |  24         | 
  | .zero.table          |  0x10009668   |  8          | 
  | .data                |  0x080022e0   |  1320       | 
  | .cy_sharedmem        |  0x08002808   |  8          | 
  | .noinit              |  0x08002810   |  148        | 
  | .bss                 |  0x080028a4   |  1324       | 
  | .heap                |  0x08002dd0   |  1030704    | 
   ---------------------------------------------------- 

  Total Internal Flash (Available)          2097152    
  Total Internal Flash (Utilized)           39848      

  Total Internal SRAM (Available)           1046528    
  Total Internal SRAM (Utilized with heap)  1033504    


Programming target device... 
Open On-Chip Debugger 0.10.0+dev-4.1.0.1058 (2020-08-11-03:45)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
adapter speed: 2000 kHz
adapter srst delay: 25
adapter srst pulse_width: 25
** Auto-acquire enabled, use "set ENABLE_ACQUIRE 0" to disable
cortex_m reset_config sysresetreq
cortex_m reset_config sysresetreq
Info : Using CMSIS loader 'CY8C6xxA_SMIF' for bank 'psoc6_smif0_cm0' (footprint 14672 bytes)
Warn : SFlash programming allowed for regions: USER, TOC, KEY
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : KitProg3: FW version: 1.14.514
Info : KitProg3: Pipelined transfers disabled, please update the firmware
Info : VTarget = 3.221 V
Info : kitprog3: acquiring the device...
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x6ba02477
Info : psoc6.cpu.cm0: hardware has 4 breakpoints, 2 watchpoints
***************************************
** Silicon: 0xE453, Family: 0x102, Rev.: 0x12 (A1)
** Detected Device: CY8C624ABZI-S2D44
** Detected Main Flash size, kb: 2048
** Flash Boot version: 3.1.0.378
** Chip Protection: NORMAL
***************************************
Info : psoc6.cpu.cm4: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for psoc6.cpu.cm0 on 3333
Info : Listening on port 3333 for gdb connections
Info : starting gdb server for psoc6.cpu.cm4 on 3334
Info : Listening on port 3334 for gdb connections
Info : SWD DPIDR 0x6ba02477
Info : kitprog3: acquiring the device...
psoc6.cpu.cm0 halted due to debug-request, current mode: Thread 
xPSR: 0x41000000 pc: 0x00000190 msp: 0x080ff800
** Device acquired successfully
** psoc6.cpu.cm4: Ran after reset and before halt...
psoc6.cpu.cm4 halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x0000012a msp: 0x080ff800
** Programming Started **
auto erase enabled
Info : Flash write discontinued at 0x1000179c, next section at 0x10002000
Info : Padding image section 0 at 0x1000179c with 100 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
Info : Padding image section 1 at 0x10009ba0 with 96 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
wrote 37888 bytes from file /Users/arh/mtb22/IoT_Expert_FreeRTOS_NTShell_Template/build/CY8CKIT-062S2-43012/Debug/MTBShellTemplate.hex in 1.402638s (26.379 KiB/s)
** Programming Finished **
** Verify Started **
verified 37692 bytes in 0.080973s (454.579 KiB/s)
** Verified OK **
** Resetting Target **
Info : SWD DPIDR 0x6ba02477
shutdown command invoked
Info : psoc6.dap: powering down debug domain...
Warn : Failed to power down Debug Domains
  
arh (master) IoT_Expert_FreeRTOS_NTShell_Template $

Add the NTShell Library & Examine New Library Structure

Everything is working and my basic project has FreeRTOS and a blinking LED.  Now let’s add the NT Shell Library.  To do this run the library manager by running “make modlibs” (or click on the button in Eclipse).  Select Libraries –> IoT Expert –> ntshell

When you press update, the library manager will do its thing again.

When I look in the “deps” directory, I see some new file types called “.mtb”.  These files tell your project where to find each of the libraries.  Notice that the middleware-ntshell.mtb points to “$$ASSET_REPO$$”.  Where is that?

If you have a aook at the Makefile it tell you that it is “../” and “mtb_shared”.

# Relative path to the shared repo location.
#
# All .mtb files have the format, <URI><COMMIT><LOCATION>. If the <LOCATION> field 
# begins with $$ASSET_REPO$$, then the repo is deposited in the path specified by 
# the CY_GETLIBS_SHARED_PATH variable. The default location is one directory level 
# above the current app directory.
# This is used with CY_GETLIBS_SHARED_NAME variable, which specifies the directory name.
CY_GETLIBS_SHARED_PATH=../

# Directory name of the shared repo location.
#
CY_GETLIBS_SHARED_NAME=mtb_shared

To start editing I will run Visual Studio Code by typing “code .”.  The first thing that happens is that it notices that this is a workspace instead of just a directory.

And when you look at the workspace you can see that it knows about both the example project as well as “mtb_shared”.  That is sweet.

Update the Project and Program

Now follow the instructions from the middlware-ntshell readme by copying “usrcmd.*” into my project.

arh (master) IoT_Expert_FreeRTOS_NTShell_Template $ cp ../mtb_shared/middleware-ntshell/latest-v2.X/template/psoc6sdk/usrcmd.* .

Then I edit main.c to

  1. #include “usrcmd.h” on line 8
  2. Start the shell task which is called “usrcmd_task” on line 39

Now buid/project by running “make -j program”

arh (master *) IoT_Expert_FreeRTOS_NTShell_Template $ make -j program
Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Prebuild operations complete
Commencing build operations...

Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Initializing build: MTBShellTemplate Debug CY8CKIT-062S2-43012 GCC_ARM

Auto-discovery in progress...
-> Found 205 .c file(s)
-> Found 46 .S file(s)
-> Found 23 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 6 .a file(s)
-> Found 503 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete

Constructing build rules...
Build rules construction complete

==============================================================================
= Building application =
==============================================================================
Generating compilation database file...
-> ./build/compile_commands.json
Compilation database file generation complete
Building 193 file(s)
    Compiling app file main.c
    Linking output file MTBShellTemplate.elf
==============================================================================
= Build complete =
==============================================================================

Calculating memory consumption: CY8C624ABZI-S2D44 GCC_ARM -Og

   ---------------------------------------------------- 
  | Section Name         |  Address      |  Size       | 
   ---------------------------------------------------- 
  | .cy_m0p_image        |  0x10000000   |  6044       | 
  | .text                |  0x10002000   |  52780      | 
  | .ARM.exidx           |  0x1000ee2c   |  8          | 
  | .copy.table          |  0x1000ee34   |  24         | 
  | .zero.table          |  0x1000ee4c   |  8          | 
  | .data                |  0x080022e0   |  1688       | 
  | .cy_sharedmem        |  0x08002978   |  8          | 
  | .noinit              |  0x08002980   |  148        | 
  | .bss                 |  0x08002a14   |  2136       | 
  | .heap                |  0x08003270   |  1029520    | 
   ---------------------------------------------------- 

  Total Internal Flash (Available)          2097152    
  Total Internal Flash (Utilized)           62716      

  Total Internal SRAM (Available)           1046528    
  Total Internal SRAM (Utilized with heap)  1033500    


Programming target device... 
Open On-Chip Debugger 0.10.0+dev-4.1.0.1058 (2020-08-11-03:45)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
adapter speed: 2000 kHz
adapter srst delay: 25
adapter srst pulse_width: 25
** Auto-acquire enabled, use "set ENABLE_ACQUIRE 0" to disable
cortex_m reset_config sysresetreq
cortex_m reset_config sysresetreq
Info : Using CMSIS loader 'CY8C6xxA_SMIF' for bank 'psoc6_smif0_cm0' (footprint 14672 bytes)
Warn : SFlash programming allowed for regions: USER, TOC, KEY
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : KitProg3: FW version: 1.14.514
Info : KitProg3: Pipelined transfers disabled, please update the firmware
Info : VTarget = 3.225 V
Info : kitprog3: acquiring the device...
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x6ba02477
Info : psoc6.cpu.cm0: hardware has 4 breakpoints, 2 watchpoints
***************************************
** Silicon: 0xE453, Family: 0x102, Rev.: 0x12 (A1)
** Detected Device: CY8C624ABZI-S2D44
** Detected Main Flash size, kb: 2048
** Flash Boot version: 3.1.0.378
** Chip Protection: NORMAL
***************************************
Info : psoc6.cpu.cm4: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for psoc6.cpu.cm0 on 3333
Info : Listening on port 3333 for gdb connections
Info : starting gdb server for psoc6.cpu.cm4 on 3334
Info : Listening on port 3334 for gdb connections
Info : SWD DPIDR 0x6ba02477
Info : kitprog3: acquiring the device...
psoc6.cpu.cm0 halted due to debug-request, current mode: Thread 
xPSR: 0x41000000 pc: 0x00000190 msp: 0x080ff800
** Device acquired successfully
** psoc6.cpu.cm4: Ran after reset and before halt...
psoc6.cpu.cm4 halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x0000012a msp: 0x080ff800
** Programming Started **
auto erase enabled
Info : Flash write discontinued at 0x1000179c, next section at 0x10002000
Info : Padding image section 0 at 0x1000179c with 100 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
Info : Padding image section 1 at 0x1000f4f4 with 268 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
wrote 60928 bytes from file /Users/arh/mtb22/IoT_Expert_FreeRTOS_NTShell_Template/build/CY8CKIT-062S2-43012/Debug/MTBShellTemplate.hex in 2.017097s (29.498 KiB/s)
** Programming Finished **
** Verify Started **
verified 60560 bytes in 0.119193s (496.175 KiB/s)
** Verified OK **
** Resetting Target **
Info : SWD DPIDR 0x6ba02477
shutdown command invoked
Info : psoc6.dap: powering down debug domain...
  
arh (master *) IoT_Expert_FreeRTOS_NTShell_Template $

Now I have a functional shell.  Here is the serial console.

Add the Task List functionality

In the main.c above I started up the usrcmd_task with a stack size of config_MINIMAL_STACK_SIZE * 4.  Where did I get that?  Well the first couple of times I did this it crashed by running out of stack so I tried bigger and bigger numbers until it stopped crashing.  This is a kind of a pain in the ass.   If you know FreeRTOS there is a function called “vTaskList” which will give you stats about the tasks.

In order to use that function you need to turn it on.  Notice that I #ifdef and #if to see if it is turned on inside of usrcmd.c

#ifdef configUSE_TRACE_FACILITY
#if configUSE_STATS_FORMATTING_FUNCTIONS ==1
static int usrcmd_list(int argc, char **argv);
#endif
#endif

So let’s turn it on by editing “FreeRTOSConfig.h” and enabling the two required defines.

#define configUSE_TRACE_FACILITY					1
#define configUSE_STATS_FORMATTING_FUNCTIONS        1

Now build/program.

arh (master *) IoT_Expert_FreeRTOS_NTShell_Template $ make -j program
Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Prebuild operations complete
Commencing build operations...

Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk

Initializing build: MTBShellTemplate Debug CY8CKIT-062S2-43012 GCC_ARM

Auto-discovery in progress...
-> Found 205 .c file(s)
-> Found 46 .S file(s)
-> Found 23 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 6 .a file(s)
-> Found 503 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete

Constructing build rules...
Build rules construction complete

==============================================================================
= Building application =
==============================================================================
Generating compilation database file...
-> ./build/compile_commands.json
Compilation database file generation complete
Building 193 file(s)
    Compiling app file lowPower.c
    Compiling app file main.c
    Compiling app file usrcmd.c
    Compiling ext file croutine.c
    Compiling ext file event_groups.c
    Compiling ext file list.c
    Compiling ext file heap_1.c
    Compiling ext file heap_2.c
    Compiling ext file heap_3.c
    Compiling ext file heap_4.c
    Compiling ext file heap_5.c
    Compiling ext file port.c
    Compiling ext file queue.c
    Compiling ext file stream_buffer.c
    Compiling ext file tasks.c
    Compiling ext file timers.c
    Compiling ext file psoc6_ntshell_port.c
    Linking output file MTBShellTemplate.elf
==============================================================================
= Build complete =
==============================================================================

Calculating memory consumption: CY8C624ABZI-S2D44 GCC_ARM -Og

   ---------------------------------------------------- 
  | Section Name         |  Address      |  Size       | 
   ---------------------------------------------------- 
  | .cy_m0p_image        |  0x10000000   |  6044       | 
  | .text                |  0x10002000   |  54876      | 
  | .ARM.exidx           |  0x1000f65c   |  8          | 
  | .copy.table          |  0x1000f664   |  24         | 
  | .zero.table          |  0x1000f67c   |  8          | 
  | .data                |  0x080022e0   |  1688       | 
  | .cy_sharedmem        |  0x08002978   |  8          | 
  | .noinit              |  0x08002980   |  148        | 
  | .bss                 |  0x08002a14   |  2136       | 
  | .heap                |  0x08003270   |  1029520    | 
   ---------------------------------------------------- 

  Total Internal Flash (Available)          2097152    
  Total Internal Flash (Utilized)           64812      

  Total Internal SRAM (Available)           1046528    
  Total Internal SRAM (Utilized with heap)  1033500    


Programming target device... 
Open On-Chip Debugger 0.10.0+dev-4.1.0.1058 (2020-08-11-03:45)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
adapter speed: 2000 kHz
adapter srst delay: 25
adapter srst pulse_width: 25
** Auto-acquire enabled, use "set ENABLE_ACQUIRE 0" to disable
cortex_m reset_config sysresetreq
cortex_m reset_config sysresetreq
Info : Using CMSIS loader 'CY8C6xxA_SMIF' for bank 'psoc6_smif0_cm0' (footprint 14672 bytes)
Warn : SFlash programming allowed for regions: USER, TOC, KEY
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : KitProg3: FW version: 1.14.514
Info : KitProg3: Pipelined transfers disabled, please update the firmware
Info : VTarget = 3.220 V
Info : kitprog3: acquiring the device...
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x6ba02477
Info : psoc6.cpu.cm0: hardware has 4 breakpoints, 2 watchpoints
***************************************
** Silicon: 0xE453, Family: 0x102, Rev.: 0x12 (A1)
** Detected Device: CY8C624ABZI-S2D44
** Detected Main Flash size, kb: 2048
** Flash Boot version: 3.1.0.378
** Chip Protection: NORMAL
***************************************
Info : psoc6.cpu.cm4: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for psoc6.cpu.cm0 on 3333
Info : Listening on port 3333 for gdb connections
Info : starting gdb server for psoc6.cpu.cm4 on 3334
Info : Listening on port 3334 for gdb connections
Info : SWD DPIDR 0x6ba02477
Info : kitprog3: acquiring the device...
psoc6.cpu.cm0 halted due to debug-request, current mode: Thread 
xPSR: 0x41000000 pc: 0x00000190 msp: 0x080ff800
** Device acquired successfully
** psoc6.cpu.cm4: Ran after reset and before halt...
psoc6.cpu.cm4 halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x0000012a msp: 0x080ff800
** Programming Started **
auto erase enabled
Info : Flash write discontinued at 0x1000179c, next section at 0x10002000
Info : Padding image section 0 at 0x1000179c with 100 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
Info : Padding image section 1 at 0x1000fd24 with 220 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
wrote 62976 bytes from file /Users/arh/mtb22/IoT_Expert_FreeRTOS_NTShell_Template/build/CY8CKIT-062S2-43012/Debug/MTBShellTemplate.hex in 2.092903s (29.385 KiB/s)
** Programming Finished **
** Verify Started **
verified 62656 bytes in 0.123619s (494.968 KiB/s)
** Verified OK **
** Resetting Target **
Info : SWD DPIDR 0x6ba02477
shutdown command invoked
Info : psoc6.dap: powering down debug domain...

When I run help you can see I have a new command called “tasks” which lists all of the tasks and their stack high water marks.

Put the Template on GitHub

I am happy with my new template.  So, I go to GitHub and create a new repository.

Then on my current project:

  1. I blow away the git history (didnt really have to do that).
  2. Create a new git repo “git init .”
  3. Add a pointer to GitHub “git remote add….”
  4. Add all of the files “git add *”
  5. Add the .gitignore “git add .gitignore”
  6. Commit the changes “git commit…”
  7. Push it to GitHub “git push …”
arh (master *) IoT_Expert_FreeRTOS_NTShell_Template $ rm -rf .git
arh IoT_Expert_FreeRTOS_NTShell_Template $ git init .
Initialized empty Git repository in /Users/arh/mtb22/IoT_Expert_FreeRTOS_NTShell_Template/.git/
arh (master #) IoT_Expert_FreeRTOS_NTShell_Template $ git remote add origin git@iotexpert.github.com:iotexpert/mtb2-freertos-ntshell-template.git
arh (master #) IoT_Expert_FreeRTOS_NTShell_Template $ git add * 
The following paths are ignored by one of your .gitignore files:
build
Use -f if you really want to add them.
arh (master #) IoT_Expert_FreeRTOS_NTShell_Template $ git add .gitignore
arh (master #) IoT_Expert_FreeRTOS_NTShell_Template $ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
	new file:   .gitignore
	new file:   FreeRTOSConfig.h
	new file:   LICENSE
	new file:   MTBShellTemplate.code-workspace
	new file:   Makefile
	new file:   README.md
	new file:   deps/TARGET_CY8CKIT-062S2-43012.mtb
	new file:   deps/freertos.mtb
	new file:   deps/middleware-ntshell.mtb
	new file:   deps/retarget-io.mtb
	new file:   global.h
	new file:   lowPower.c
	new file:   main.c
	new file:   openocd.tcl
	new file:   usrcmd.c
	new file:   usrcmd.h

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.vscode/

arh (master #) IoT_Expert_FreeRTOS_NTShell_Template $ git commit -m "Initial commit"
[master (root-commit) 26b5d3c] Initial commit
 16 files changed, 994 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 FreeRTOSConfig.h
 create mode 100644 LICENSE
 create mode 100644 MTBShellTemplate.code-workspace
 create mode 100644 Makefile
 create mode 100644 README.md
 create mode 100644 deps/TARGET_CY8CKIT-062S2-43012.mtb
 create mode 100644 deps/freertos.mtb
 create mode 100644 deps/middleware-ntshell.mtb
 create mode 100644 deps/retarget-io.mtb
 create mode 100644 global.h
 create mode 100644 lowPower.c
 create mode 100644 main.c
 create mode 100644 openocd.tcl
 create mode 100644 usrcmd.c
 create mode 100644 usrcmd.h
arh (master) IoT_Expert_FreeRTOS_NTShell_Template $ git push -u origin master
Enumerating objects: 19, done.
Counting objects: 100% (19/19), done.
Delta compression using up to 12 threads
Compressing objects: 100% (19/19), done.
Writing objects: 100% (19/19), 16.21 KiB | 5.40 MiB/s, done.
Total 19 (delta 0), reused 0 (delta 0)
To iotexpert.github.com:iotexpert/mtb2-freertos-ntshell-template.git
 * [new branch]      master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.
arh (master) IoT_Expert_FreeRTOS_NTShell_Template $

Update the Manifests

To get access to the new template I need to add it to the IoT Expert App Manifest.  I edit the xml file to have the new app

<apps>
  <app>
    <name>IoT Expert FreeRTOS Template</name>
    <id>mtb2-freertos-template</id>
    <uri>https://github.com/iotexpert/mtb2-freertos-template</uri>
    <description>This template provide a starting point for FreeRTOS projects.  Including a starting blinking LED task</description>
    <req_capabilities>psoc6</req_capabilities>
    <versions>
      <version>
        <num>Latest 1.X release</num>
        <commit>master</commit>
      </version>
    </versions>
  </app>
    <app>
    <name>IoT Expert FreeRTOS NTShell Template</name>
    <id>mtb2-freertos-ntshell-template</id>
    <uri>https://github.com/iotexpert/mtb2-freertos-ntshell-template</uri>
    <description>This template provide a starting point for FreeRTOS projects.  Including a starting blinking LED task and shell</description>
    <req_capabilities>psoc6</req_capabilities>
    <versions>
      <version>
        <num>Latest 1.X release</num>
        <commit>master</commit>
      </version>
    </versions>
  </app>
</apps>

Now I need to git add, git commit and git push it to GitHub.

arh (master) mtb2-iotexpert-manifests $ code .
arh (master) mtb2-iotexpert-manifests $ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   iotexpert-app-manifest.xml

no changes added to commit (use "git add" and/or "git commit -a")
arh (master *) mtb2-iotexpert-manifests $ git add iotexpert-app-manifest.xml
arh (master +) mtb2-iotexpert-manifests $ git commit -m "Updated with ntshell example"
[master 47a7bb1] Updated with ntshell example
 1 file changed, 13 insertions(+)
arh (master) mtb2-iotexpert-manifests $ git push
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 554 bytes | 554.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To iotexpert.github.com:iotexpert/mtb2-iotexpert-manifests.git
   28ed2d0..47a7bb1  master -> master

Test the new Template

Everything should be working so make a new project.

Cool.  There is the new template.

When I program it… everything is cool.

arh (master) TestNTS $ make -j program
Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk
Prebuild operations complete
Commencing build operations...
Tools Directory: /Applications/ModusToolbox/tools_2.2
CY8CKIT-062S2-43012.mk: ../mtb_shared/TARGET_CY8CKIT-062S2-43012/latest-v2.X/CY8CKIT-062S2-43012.mk
Initializing build: MTBShellTemplate Debug CY8CKIT-062S2-43012 GCC_ARM
Auto-discovery in progress...
-> Found 205 .c file(s)
-> Found 46 .S file(s)
-> Found 23 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 6 .a file(s)
-> Found 503 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete
Constructing build rules...
Build rules construction complete
==============================================================================
= Building application =
==============================================================================
Generating compilation database file...
-> ./build/compile_commands.json
Compilation database file generation complete
Building 193 file(s)
Compiling app file lowPower.c
Compiling app file main.c
Compiling app file usrcmd.c
Compiling ext file startup_psoc6_02_cm4.S
Compiling ext file cy_syslib_gcc.S
Compiling ext file cycfg.c
Compiling ext file cycfg_capsense.c
Compiling ext file cycfg_clocks.c
Compiling ext file cycfg_peripherals.c
Compiling ext file cycfg_pins.c
Compiling ext file cycfg_qspi_memslot.c
Compiling ext file cycfg_routing.c
Compiling ext file cycfg_system.c
Compiling ext file system_psoc6_cm4.c
Compiling ext file cybsp.c
Compiling ext file cy_capsense_centroid.c
Compiling ext file cy_capsense_control.c
Compiling ext file cy_capsense_csd.c
Compiling ext file cy_capsense_csx.c
Compiling ext file cy_capsense_filter.c
Compiling ext file cy_capsense_processing.c
Compiling ext file cy_capsense_selftest.c
Compiling ext file cy_capsense_sensing.c
Compiling ext file cy_capsense_structure.c
Compiling ext file cy_capsense_tuner.c
Compiling ext file croutine.c
Compiling ext file event_groups.c
Compiling ext file list.c
Compiling ext file heap_1.c
Compiling ext file heap_2.c
Compiling ext file heap_3.c
Compiling ext file heap_4.c
Compiling ext file heap_5.c
Compiling ext file port.c
Compiling ext file queue.c
Compiling ext file stream_buffer.c
Compiling ext file tasks.c
Compiling ext file timers.c
Compiling ext file ntlibc.c
Compiling ext file ntshell.c
Compiling ext file text_editor.c
Compiling ext file text_history.c
Compiling ext file vtrecv.c
Compiling ext file vtsend.c
Compiling ext file psoc6_ntshell_port.c
Compiling ext file ntopt.c
Compiling ext file ntstdio.c
Compiling ext file cyhal_adc.c
Compiling ext file cyhal_analog_common.c
Compiling ext file cyhal_clock.c
Compiling ext file cyhal_comp.c
Compiling ext file cyhal_comp_ctb.c
Compiling ext file cyhal_comp_lp.c
Compiling ext file cyhal_crc.c
Compiling ext file cyhal_crypto_common.c
Compiling ext file cyhal_dac.c
Compiling ext file cyhal_deprecated.c
Compiling ext file cyhal_dma.c
Compiling ext file cyhal_dma_dmac.c
Compiling ext file cyhal_dma_dw.c
Compiling ext file cyhal_ezi2c.c
Compiling ext file cyhal_flash.c
Compiling ext file cyhal_gpio.c
Compiling ext file cyhal_hwmgr.c
Compiling ext file cyhal_i2c.c
Compiling ext file cyhal_i2s.c
Compiling ext file cyhal_interconnect.c
Compiling ext file cyhal_lptimer.c
Compiling ext file cyhal_not_implemented.c
Compiling ext file cyhal_opamp.c
Compiling ext file cyhal_pdmpcm.c
Compiling ext file cyhal_pwm.c
Compiling ext file cyhal_qspi.c
Compiling ext file cyhal_rtc.c
Compiling ext file cyhal_scb_common.c
Compiling ext file cyhal_sdhc.c
Compiling ext file cyhal_spi.c
Compiling ext file cyhal_syspm.c
Compiling ext file cyhal_system.c
Compiling ext file cyhal_tcpwm_common.c
Compiling ext file cyhal_timer.c
Compiling ext file cyhal_trng.c
Compiling ext file cyhal_uart.c
Compiling ext file cyhal_udb_sdio.c
Compiling ext file cyhal_usb_dev.c
Compiling ext file cyhal_utils.c
Compiling ext file cyhal_wdt.c
Compiling ext file cyhal_psoc6_01_104_m_csp_ble.c
Compiling ext file cyhal_psoc6_01_104_m_csp_ble_usb.c
Compiling ext file cyhal_psoc6_01_116_bga_ble.c
Compiling ext file cyhal_psoc6_01_116_bga_usb.c
Compiling ext file cyhal_psoc6_01_124_bga.c
Compiling ext file cyhal_psoc6_01_124_bga_sip.c
Compiling ext file cyhal_psoc6_01_43_smt.c
Compiling ext file cyhal_psoc6_01_68_qfn_ble.c
Compiling ext file cyhal_psoc6_01_80_wlcsp.c
Compiling ext file cyhal_psoc6_02_100_wlcsp.c
Compiling ext file cyhal_psoc6_02_124_bga.c
Compiling ext file cyhal_psoc6_02_128_tqfp.c
Compiling ext file cyhal_psoc6_02_68_qfn.c
Compiling ext file cyhal_psoc6_03_100_tqfp.c
Compiling ext file cyhal_psoc6_03_49_wlcsp.c
Compiling ext file cyhal_psoc6_03_68_qfn.c
Compiling ext file cyhal_psoc6_04_64_tqfp.c
Compiling ext file cyhal_psoc6_04_68_qfn.c
Compiling ext file cyhal_psoc6_04_80_tqfp.c
Compiling ext file cyhal_triggers_psoc6_01.c
Compiling ext file cyhal_triggers_psoc6_02.c
Compiling ext file cyhal_triggers_psoc6_03.c
Compiling ext file cyhal_triggers_psoc6_04.c
Compiling ext file cy_ble_clk.c
Compiling ext file cy_canfd.c
Compiling ext file cy_crypto.c
Compiling ext file cy_crypto_core_aes_v1.c
Compiling ext file cy_crypto_core_aes_v2.c
Compiling ext file cy_crypto_core_cmac_v1.c
Compiling ext file cy_crypto_core_cmac_v2.c
Compiling ext file cy_crypto_core_crc_v1.c
Compiling ext file cy_crypto_core_crc_v2.c
Compiling ext file cy_crypto_core_des_v1.c
Compiling ext file cy_crypto_core_des_v2.c
Compiling ext file cy_crypto_core_ecc_domain_params.c
Compiling ext file cy_crypto_core_ecc_ecdsa.c
Compiling ext file cy_crypto_core_ecc_key_gen.c
Compiling ext file cy_crypto_core_ecc_nist_p.c
Compiling ext file cy_crypto_core_hmac_v1.c
Compiling ext file cy_crypto_core_hmac_v2.c
Compiling ext file cy_crypto_core_hw.c
Compiling ext file cy_crypto_core_hw_v1.c
Compiling ext file cy_crypto_core_mem_v1.c
Compiling ext file cy_crypto_core_mem_v2.c
Compiling ext file cy_crypto_core_prng_v1.c
Compiling ext file cy_crypto_core_prng_v2.c
Compiling ext file cy_crypto_core_rsa.c
Compiling ext file cy_crypto_core_sha_v1.c
Compiling ext file cy_crypto_core_sha_v2.c
Compiling ext file cy_crypto_core_trng_v1.c
Compiling ext file cy_crypto_core_trng_v2.c
Compiling ext file cy_crypto_core_vu.c
Compiling ext file cy_crypto_server.c
Compiling ext file cy_csd.c
Compiling ext file cy_ctb.c
Compiling ext file cy_ctdac.c
Compiling ext file cy_device.c
Compiling ext file cy_dma.c
Compiling ext file cy_dmac.c
Compiling ext file cy_efuse.c
Compiling ext file cy_flash.c
Compiling ext file cy_gpio.c
Compiling ext file cy_i2s.c
Compiling ext file cy_ipc_drv.c
Compiling ext file cy_ipc_pipe.c
Compiling ext file cy_ipc_sema.c
Compiling ext file cy_lpcomp.c
Compiling ext file cy_lvd.c
Compiling ext file cy_mcwdt.c
Compiling ext file cy_pdm_pcm.c
Compiling ext file cy_pra.c
Compiling ext file cy_pra_cfg.c
Compiling ext file cy_profile.c
Compiling ext file cy_prot.c
Compiling ext file cy_rtc.c
Compiling ext file cy_sar.c
Compiling ext file cy_scb_common.c
Compiling ext file cy_scb_ezi2c.c
Compiling ext file cy_scb_i2c.c
Compiling ext file cy_scb_spi.c
Compiling ext file cy_scb_uart.c
Compiling ext file cy_sd_host.c
Compiling ext file cy_seglcd.c
Compiling ext file cy_smartio.c
Compiling ext file cy_smif.c
Compiling ext file cy_smif_memslot.c
Compiling ext file cy_sysanalog.c
Compiling ext file cy_sysclk.c
Compiling ext file cy_sysint.c
Compiling ext file cy_syslib.c
Compiling ext file cy_syspm.c
Compiling ext file cy_systick.c
Compiling ext file cy_tcpwm_counter.c
Compiling ext file cy_tcpwm_pwm.c
Compiling ext file cy_tcpwm_quaddec.c
Compiling ext file cy_tcpwm_shiftreg.c
Compiling ext file cy_trigmux.c
Compiling ext file cy_usbfs_dev_drv.c
Compiling ext file cy_usbfs_dev_drv_io.c
Compiling ext file cy_usbfs_dev_drv_io_dma.c
Compiling ext file cy_wdt.c
Compiling ext file psoc6_01_cm0p_sleep.c
Compiling ext file psoc6_02_cm0p_sleep.c
Compiling ext file psoc6_03_cm0p_sleep.c
Compiling ext file psoc6_04_cm0p_sleep.c
Compiling ext file cy_retarget_io.c
Linking output file MTBShellTemplate.elf
==============================================================================
= Build complete =
==============================================================================
Calculating memory consumption: CY8C624ABZI-S2D44 GCC_ARM -Og
---------------------------------------------------- 
| Section Name         |  Address      |  Size       | 
---------------------------------------------------- 
| .cy_m0p_image        |  0x10000000   |  6044       | 
| .text                |  0x10002000   |  54876      | 
| .ARM.exidx           |  0x1000f65c   |  8          | 
| .copy.table          |  0x1000f664   |  24         | 
| .zero.table          |  0x1000f67c   |  8          | 
| .data                |  0x080022e0   |  1688       | 
| .cy_sharedmem        |  0x08002978   |  8          | 
| .noinit              |  0x08002980   |  148        | 
| .bss                 |  0x08002a14   |  2136       | 
| .heap                |  0x08003270   |  1029520    | 
---------------------------------------------------- 
Total Internal Flash (Available)          2097152    
Total Internal Flash (Utilized)           64812      
Total Internal SRAM (Available)           1046528    
Total Internal SRAM (Utilized with heap)  1033500    
Programming target device... 
Open On-Chip Debugger 0.10.0+dev-4.1.0.1058 (2020-08-11-03:45)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
adapter speed: 2000 kHz
adapter srst delay: 25
adapter srst pulse_width: 25
** Auto-acquire enabled, use "set ENABLE_ACQUIRE 0" to disable
cortex_m reset_config sysresetreq
cortex_m reset_config sysresetreq
Info : Using CMSIS loader 'CY8C6xxA_SMIF' for bank 'psoc6_smif0_cm0' (footprint 14672 bytes)
Warn : SFlash programming allowed for regions: USER, TOC, KEY
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : KitProg3: FW version: 1.14.514
Info : KitProg3: Pipelined transfers disabled, please update the firmware
Info : VTarget = 3.221 V
Info : kitprog3: acquiring the device...
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x6ba02477
Info : psoc6.cpu.cm0: hardware has 4 breakpoints, 2 watchpoints
***************************************
** Silicon: 0xE453, Family: 0x102, Rev.: 0x12 (A1)
** Detected Device: CY8C624ABZI-S2D44
** Detected Main Flash size, kb: 2048
** Flash Boot version: 3.1.0.378
** Chip Protection: NORMAL
***************************************
Info : psoc6.cpu.cm4: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for psoc6.cpu.cm0 on 3333
Info : Listening on port 3333 for gdb connections
Info : starting gdb server for psoc6.cpu.cm4 on 3334
Info : Listening on port 3334 for gdb connections
Info : SWD DPIDR 0x6ba02477
Info : kitprog3: acquiring the device...
psoc6.cpu.cm0 halted due to debug-request, current mode: Thread 
xPSR: 0x41000000 pc: 0x00000190 msp: 0x080ff800
** Device acquired successfully
** psoc6.cpu.cm4: Ran after reset and before halt...
psoc6.cpu.cm4 halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x0000012a msp: 0x080ff800
** Programming Started **
auto erase enabled
Info : Flash write discontinued at 0x1000179c, next section at 0x10002000
Info : Padding image section 0 at 0x1000179c with 100 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
Info : Padding image section 1 at 0x1000fd24 with 220 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
wrote 62976 bytes from file /Users/arh/mtb22/TestNTS/build/CY8CKIT-062S2-43012/Debug/MTBShellTemplate.hex in 2.082329s (29.534 KiB/s)
** Programming Finished **
** Verify Started **
verified 62656 bytes in 0.122516s (499.425 KiB/s)
** Verified OK **
** Resetting Target **
Info : SWD DPIDR 0x6ba02477
shutdown command invoked
Info : psoc6.dap: powering down debug domain...
arh (master) TestNTS $

And the project seems to be doing the needful.

PSoC 6 SDK OneWire Bus (Part 5): Round out the OWB driver

Summary

This article shows the completion of the PSoC 6 SDK One Wire Bus library.  It shows the test apparatus for evaluating DS18B20 sensors.

Article
PSoC 6 SDK OneWire Bus (Part 1) : Build Basic Project
PSoC 6 SDK OneWire Bus (Part 2) : Implement Read & Write
PSoC 6 SDK OneWire Bus (Part 3) : Remove Busy Wait & Debug
PSoC 6 SDK OneWire Bus (Part 4): But, Can it Read the Temperature?
PSoC 6 SDK OneWire Bus (Part 5): Round out the OWB Driver

Story

If you remember from the previous articles, I created the one wire bus library by looking at the function calls in the DS18B20 library and reverse engineering the function prototypes.  And, as I said in the earlier article, it would have been way better to just look at the David Antliff “OWB” library.  But that is not how it went down.  I wonder how much time in the world is wasted by programmer re-implementing code that already exists?

After the first four articles, I had three functions which the DS18B20 library defined, but I had not yet implemented.

owb_ret_t owb_write_rom_code(OneWireBus *bus, OneWireBus_ROMCode romcode);
owb_ret_t owb_crc8_bytes(uint32_t val, uint8_t *buffer, uint32_t length);
void   owb_set_strong_pullup( OneWireBus *bus, bool val);

I had not implemented them because I was not totally sure how they worked.  So, I decided to go back to GitHub and see what David had done originally.  When I got to the GitHub site, https://github.com/DavidAntliff/esp32-owb/blob/master/include/owb.h, there were actually quite a few functions in his owb library that I had not implemented.

Here is the list:

owb_ret_t owb_use_crc(OneWireBus * bus, bool use_crc);
owb_ret_t owb_use_parasitic_power(OneWireBus * bus, bool use_parasitic_power);
owb_ret_t owb_use_strong_pullup_gpio(OneWireBus * bus, cyhal_gpio_t gpio);
owb_ret_t owb_read_rom(OneWireBus * bus, OneWireBus_ROMCode * rom_code);
owb_ret_t owb_verify_rom(OneWireBus * bus, OneWireBus_ROMCode *rom_code, bool * is_present);
owb_ret_t owb_write_rom_code(OneWireBus * bus, OneWireBus_ROMCode *rom_code);
uint8_t owb_crc8_byte(uint8_t crc, uint8_t data);
uint8_t owb_crc8_bytes(uint8_t crc, const uint8_t * data, size_t len);
owb_ret_t owb_search_first(OneWireBus * bus, OneWireBus_SearchState * state, bool *found_device);
owb_ret_t owb_search_next(OneWireBus * bus, OneWireBus_SearchState * state, bool *found_device);
char * owb_string_from_rom_code(OneWireBus_ROMCode *rom_code, char * buffer, size_t len);
owb_ret_t owb_set_strong_pullup(OneWireBus * bus, bool enable);

In this article I will create and/or copy the missing functions.  As I look through his implementation I also notice that we have some style differences that I will discuss.  In general I will say that his implementation is very good and any place that I did something different was just a matter of programming taste.

I was originally planning on this article taking you linearly through how I did the changes, but in reality I jumped around while I was doing the changes, that approach won’t work.  Here is the list of what I did:

  1. Add Doxygen Function Headers
  2. Move Logging Function to Library
  3. Change Commands to Enumerated Type
  4. Change Const Bus Pointer
  5. Pack the Structures
  6. Pass Structures as Pointers
  7. Driver Functions
  8. Test the Search
  9. Test the Parastitic Power

Doxygen Headers

I like using documentation that has been generated with Doxygen.  Specifically I like that the documentation is written “at the point of attack”.  But I have never actually used or generated it using Doxygen.  To make the documentation you need to put comments into your c-header files in the right format.  Here is an example from owb.h

/**
* @brief Represents a set of the legal one wire bus commands
*/
typedef enum {
OWB_ROM_SEARCH        =0xF0,  ///< Perform Search ROM cycle to identify devices on the bus
OWB_ROM_READ          =0x33,  ///< Read device ROM (single device on bus only)
OWB_ROM_MATCH         =0x55,  ///< Address a specific device on the bus by ROM
OWB_ROM_SKIP          =0xCC,  ///< Address all devices on the bus simultaneously
OWB_ROM_SEARCH_ALARM  =0xEC,  ///< Address all devices on the bus with a set alarm flag
} owb_commands_t;

In this case, David had done most of the work already and all I needed to do was copy/modify his headers in the few places where we had differences in the public interface to the library.  After that, I ran doxygen.  When I first did this I got an absolute boatload of warnings about places where I had not documented with comments.  If Hassane is reading he will say … “Really Alan didn’t write comments, imagine that”

arh (master *) p6sdk-onewire $ doxygen
Doxygen version used: 1.8.18
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
Searching for files to exclude
Searching INPUT for files to process...
Searching for files in directory /Users/arh/proj/owb-ds18b20/DS18B20Test/p6sdk-onewire
Reading and parsing tag files
Parsing files
Reading /Users/arh/proj/owb-ds18b20/DS18B20Test/p6sdk-onewire/README.md...
Preprocessing /Users/arh/proj/owb-ds18b20/DS18B20Test/p6sdk-onewire/owb.c...
Parsing file /Users/arh/proj/owb-ds18b20/DS18B20Test/p6sdk-onewire/owb.c...
Preprocessing /Users/arh/proj/owb-ds18b20/DS18B20Test/p6sdk-onewire/owb.h...
Parsing file /Users/arh/proj/owb-ds18b20/DS18B20Test/p6sdk-onewire/owb.h...
Building group list...
Building directory list...
Building namespace list...
Building file list...
Building class list...
Computing nesting relations for classes...
Associating documentation with classes...
Building example list...
Searching for enumerations...
Searching for documented typedefs...
Searching for members imported via using declarations...
Searching for included using directives...
Searching for documented variables...
Building interface member list...
Building member list...
Searching for friends...
Searching for documented defines...
Computing class inheritance relations...
Computing class usage relations...
Flushing cached template relations that have become invalid...
Computing class relations...
Add enum values to enums...
Searching for member function documentation...
Creating members for template instances...
Building page list...
Search for main page...
Computing page relations...
Determining the scope of groups...
Sorting lists...
Determining which enums are documented
Computing member relations...
Building full member lists recursively...
Adding members to member groups.
Computing member references...
Inheriting documentation...
Generating disk names...
Adding source references...
Adding xrefitems...
Sorting member lists...
Setting anonymous enum type...
Computing dependencies between directories...
Generating citations page...
Counting members...
Counting data structures...
Resolving user defined references...
Finding anchors and sections in the documentation...
Transferring function references...
Combining using relations...
Adding members to index pages...
Correcting members for VHDL...
Generating style sheet...
Generating search indices...
Generating example documentation...
Generating file sources...
Generating code for file owb.h...
Generating file documentation...
Generating docs for file owb.h...
Generating page documentation...
Generating docs for page md_README...
Generating group documentation...
Generating class documentation...
Generating docs for compound OneWireBus...
Generating docs for compound OneWireBus_ROMCode...
Generating docs for nested compound OneWireBus_ROMCode::fields...
Generating docs for compound OneWireBus_SearchState...
Generating namespace index...
Generating graph info page...
Generating directory documentation...
Generating index page...
Generating page index...
Generating module index...
Generating namespace index...
Generating namespace member index...
Generating annotated compound index...
Generating alphabetical compound index...
Generating hierarchical class index...
Generating member index...
Generating file index...
Generating file member index...
Generating example index...
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
lookup cache used 45/65536 hits=385 misses=48
finished...
arh (master *) p6sdk-onewire $

Now I have some documentation

I will say that I wish I had a few days to really learn Doxygen as there are many many many options which I have no idea what they do.  Oh well.

Fix the Logging Function

David built the library on top of the ESP32 libraries.  This included calls to the ESP32 logging library “log.h/.c“.  All through his library he calls “ESP_LOG” like this.

ESP_LOGE(TAG, "bus is NULL");

When I first looked at this I decided to just do this to make the error messages go away.  This is just a trick that will use the c-preprocessor to replace the function call to “ESP32_LOGE” with NOTHING

#define ESP_LOGE(...)

After I sorted everything else out I went back to decide what to do.  My choices were

  1. Clone the Espressif library and “fix it”
  2. Implement the functions that David used in the OWB library
  3. Find another library

I decided to use option 3 – a logging library that I found on GitHub called “log.c” (which is a very unfortunate name when you clone it).  It is really simple and works well.  Since the Tour de France is going as I write this article I will say “chappeau rxi”.  This library is written in C99 (just normal C) and has functions which can easily replace the ESP_LOG functions.  I add it to my project with “git clone git@github.com:rxi/log.c.git”

log_trace(const char *fmt, ...);
log_debug(const char *fmt, ...);
log_info(const char *fmt, ...);
log_warn(const char *fmt, ...);
log_error(const char *fmt, ...);
log_fatal(const char *fmt, ...);

This means that I just replace “ESP_LOGE” with “log_error”.  In reality rxi did something very nice by using a feature of the compiler to insert the file/line numbers.

#define log_trace(...) log_log(LOG_TRACE, __FILE__, __LINE__, __VA_ARGS__)

This only left me with the function

ESP_LOG_BUFFER_HEX_LEVEL(TAG, scratchpad, count, ESP_LOG_DEBUG);

Which I decided to do something cheap to solve.  The original code was:

              //ESP_LOG_BUFFER_HEX_LEVEL(TAG, &scratchpad->trigger_high, 3, ESP_LOG_DEBUG);

And I replaced the two uses with:

log_debug( "scratchpad write 3 bytes:%02X%02X%02X",scratchpad[0],scratchpad[1],scratchpad[2]);

and

                //ESP_LOG_BUFFER_HEX_LEVEL(TAG, scratchpad, count, ESP_LOG_DEBUG);
log_debug( "%02X%02X%02X%02X%02X%02X%02X%02X%02X",
scratchpad[0],scratchpad[1],scratchpad[2],
scratchpad[3],scratchpad[4],scratchpad[5],
scratchpad[6],scratchpad[7],scratchpad[8]);

I know it isn’t beautiful what I did, but it works.

Enumerated Command Type

When I examined the original source code, the one-wire commands were defined using #defines.

// ROM commands
#define OWB_ROM_SEARCH        0xF0  ///< Perform Search ROM cycle to identify devices on the bus
#define OWB_ROM_READ          0x33  ///< Read device ROM (single device on bus only)
#define OWB_ROM_MATCH         0x55  ///< Address a specific device on the bus by ROM
#define OWB_ROM_SKIP          0xCC  ///< Address all devices on the bus simultaneously
#define OWB_ROM_SEARCH_ALARM  0xEC  ///< Address all devices on the bus with a set alarm flag

When I did the implementation originally I chose to make the #defines into an enumerated list.  I suppose that it doesn’t really matter.  But, by enumerating the values it lets the compiler help you in situations like a switch or a function call.

typedef enum {
OWB_ROM_SEARCH        =0xF0,  ///< Perform Search ROM cycle to identify devices on the bus
OWB_ROM_READ          =0x33,  ///< Read device ROM (single device on bus only)
OWB_ROM_MATCH         =0x55,  ///< Address a specific device on the bus by ROM
OWB_ROM_SKIP          =0xCC,  ///< Address all devices on the bus simultaneously
OWB_ROM_SEARCH_ALARM  =0xEC,  ///< Address all devices on the bus with a set alarm flag
} owb_commands_t;

Const Bus pointer

Through out the original one wire bus library, the bus pointer is defined as const.  Like this:

owb_status owb_read_rom(const OneWireBus * bus, OneWireBus_ROMCode * rom_code)

But, I wanted to use the OneWireBus structure to also store some context.  By context I mean variables (which can change) but hold state for the bus.  This included the semaphore that I used to fix the delay functions.

/**
* @brief Structure containing 1-Wire bus information relevant to a single instance.
*/
typedef struct  
{
cyhal_gpio_t  pin;                   ///<Pin that the bus is attached to
cyhal_gpio_t strong_pullup_gpio;     ///<Pin that the pullup gpio is attached to
bool use_parasitic_power;            ///<Driver is using parastic power mode
bool use_crc;                        ///<Enable the use of crc checks on the ROM
// Internal use only
bool is_init;                        ///<Private
bool detect;                         ///<Private
SemaphoreHandle_t signalSemaphore;   ///<Private
cyhal_timer_t bitTimer;              ///<Private
SemaphoreHandle_t owb_num_active;    ///<Private
uint8_t scratchBitValue;             ///<Private
} OneWireBus;

ROM Code Structure Packed

In the original library the ROMCode is a union that allows access to individual bytes, or the actual data.

typedef union
{
/// Provides access via field names
struct fields
{
uint8_t family[1];         ///< family identifier (1 byte, LSB - read/write first)
uint8_t serial_number[6];  ///< serial number (6 bytes)
uint8_t crc[1];            ///< CRC check byte (1 byte, MSB - read/write last)
} __PACKED fields;             ///< Provides access via field names
uint8_t bytes[8];              ///< Provides raw byte access
} OneWireBus_ROMCode;

The problem is there is no guarantee that the compiler will pack the family, serial number and crc.  You should tell it to with the __PACKED macro.  I would say that I think that David got luck that there was not a bug.

/**
* @brief Represents a 1-Wire ROM Code. This is a sequence of eight bytes, where
*        the first byte is the family number, then the following 6 bytes form the
*        serial number. The final byte is the CRC8 check byte.
*/
typedef union
{
/// Provides access via field names
struct fields
{
uint8_t family[1];         ///< family identifier (1 byte, LSB - read/write first)
uint8_t serial_number[6];  ///< serial number (6 bytes)
uint8_t crc[1];            ///< CRC check byte (1 byte, MSB - read/write last)
} __PACKED fields;             ///< Provides access via field names
uint8_t bytes[8];              ///< Provides raw byte access
} OneWireBus_ROMCode;

C-Programming: Passing Structures as Function Arguments

In the original library David passed the rom_code structure as an argument on the stack.  But, because I started programming in the days before it was legal to pass a structure as a function argument when I did the implementation I passed a pointer.

owb_status owb_verify_rom(const OneWireBus * bus, OneWireBus_ROMCode rom_code, bool * is_present);

I wrote

owb_ret_t owb_verify_rom(OneWireBus * bus, OneWireBus_ROMCode *rom_code, bool * is_present);

Which meant that he could write

        OneWireBus_SearchState state = {
.rom_code = rom_code,
.last_discrepancy = 64,
.last_device_flag = false,
};

but I had to write

        OneWireBus_SearchState state = {
//.rom_code = rom_code,
.last_discrepancy = 64,
.last_device_flag = false,
};
memcpy(&state.rom_code,rom_code,sizeof(OneWireBus_ROMCode));

In this case it doesn’t really matter as the structure is small.

Driver Functions

If you look at the original implementation the author has a “driver”

typedef struct
{
const struct _OneWireBus_Timing * timing;   ///< Pointer to timing information
bool use_crc;                               ///< True if CRC checks are to be used when retrieving information from a device on the bus
bool use_parasitic_power;                   ///< True if parasitic-powered devices are expected on the bus
gpio_num_t strong_pullup_gpio;              ///< Set if an external strong pull-up circuit is required
const struct owb_driver * driver;           ///< Pointer to hardware driver instance
} OneWireBus;

Which is a structure with function pointers to talk to bus.

/** NOTE: Driver assumes that (*init) was called prior to any other methods */
struct owb_driver
{
/** Driver identification **/
const char* name;
/** Pointer to driver uninitialization function **/
owb_status (*uninitialize)(const OneWireBus * bus);
/** Pointer to driver reset functio **/
owb_status (*reset)(const OneWireBus * bus, bool *is_present);
/** NOTE: The data is shifted out of the low bits, eg. it is written in the order of lsb to msb */
owb_status (*write_bits)(const OneWireBus *bus, uint8_t out, int number_of_bits_to_write);
/** NOTE: Data is read into the high bits, eg. each bit read is shifted down before the next bit is read */
owb_status (*read_bits)(const OneWireBus *bus, uint8_t *in, int number_of_bits_to_read);
};

Which meant that he did this:

bus->driver->read_bits(bus, &id_bit, 1);
bus->driver->read_bits(bus, &cmp_id_bit, 1);

In my implementation I wrote functions for those things.

owb_read_bit(bus,&id_bit);
owb_read_bit(bus,&cmp_id_bit);

I don’t really think that it helped abstract the hardware because he also did this.

            gpio_set_level(bus->strong_pullup_gpio, enable ? 1 : 0);

Perhaps a driver with function pointers would have made the original port easier if I had started there?  But if so, it would have required more adherence to the original  architecture.

Test Search

A nice thing that came with his library was an implementation of the search feature which allows multiple devices to be attached to the bus.  To test this I added two sensors.

Then made a command in my console to run the test.

static int usrcmd_search(int argc, char **argv)
{
printf("Search\n");
OneWireBus_SearchState state;
bool found_device;
owb_search_first(&bus, &state, &found_device);
do {
if(found_device)
{
printf("Found Device = ");
for(int i=0;i<8;i++)
{
printf("%02X ",state.rom_code.bytes[i]);
}
printf("\n");
}
owb_search_next(&bus, &state, &found_device);
} while(found_device);
printf("Search done\n");
return 0;
}

Which worked perfectly.

Parasitic Power

I would like to test the functionality of the parasitic power.  Here is a schematic from the data sheet of how it work.  But I don’t have that transistor so that will be left for another day.

What is Next?

There are several things that I should do.

  1. Fix up the libraries to use the manifest files so they are available all of the time
  2. Fix up the libraries to use the dependency scheme
  3. Test the parasitic power
  4. Test the actual DS18B20 library (the original point of this whole thing)

I have found myself in the middle of a bunch of other problems, so these things will need to happen another day.

PSoC 6 Pins & the SPI Port

Summary

Recently, I have been helping a reader sort out some code that makes strings of WS2812 LEDs work.  Specifically, this code takes data from a frame buffer inside of the PSoC 6 and drives it out a SPI port via the MOSI pin. I have written about this a couple of times, but,  the new wrinkle in our code is that it allows you to use any combination of SPI port/pins on the chip.  Instead of using the configurators to setup the SPI to GPIO connection, I setup the connection using PDL to talk directly to the PSoC 6 configuration the registers.

Perhaps it is obvious to everyone how a connection from a peripheral to a GPIO works, but I thought that I would write about it anyway.  In this article I am going to show you a bunch of the documentation for PSoC as well as the PDL source code which implements the documentation.  Specifically, I will show you the PSoC 6

  1. Architecture TRM
  2. Register TRM
  3. Datasheet
  4. PDL

Architecture TRM

In the picture below, which I copied from the PSoC 6 Architecture TRM, you can see how an individual GPIO works.  Starting  at the Pin of the chip you can see that there are three connections from/to the pin (look at the green box).

  • A set of switches to/from the Analog Mux Bus which enable CapSense or Analog peripherals to talk to the Pin
  • A connection from the pin to the Analog peripherals (some Analog peripherals can attach directly to a pin and not though the Analog Mux Bus
  • A connection to the High Speed I/O Matrix (HSIOM) – for the digital peripherals

Notice that all of the signals coming into the green box from the top are DIGITAL.  All of the signals coming into the box from the bottom are Analog and the line coming into the middle of the box controls the behavior of the I/O.

For my case the SPI is one of the “Fixed Function Digital Peripherals”.  In order to get it to connect to the pin I will beed to pick out the right signal in the multiplexer that is in the HSIOM Matrix box.

When you scroll down a little bit further in the Architecture TRM, the next diagram is a more detailed description of the GPIO.  Notice that there are a bunch of configuration register bits which setup different parts of the I/O like slew rate, interrupts, drive mode etc.  Notice that the multiplexer that is connected to “out”
and “out_en” has a bunch of different possible signals.  Including “GPIO_PRTx_OUT[OUTy]” which is a register bit which is can be used for “digital write”.  For instance GPIO_PRT0_OUT[2] would be P0_2.  The other interesting thing going on here is you can see that there are really three classes of signals attached to the mutiplexer

  • The digital output pin
  • Active signals – which work while the chip is not in deep sleep
  • Deep Sleep signals – which work while the chip is in deep sleep.

On the output side you can see the two pullup and pulldown resistors, as well as the two transistors which pullup and pull down.  All of these can be configured to be connected… or not.

And finally at the bottom of the I/O you can see the analog signals.

 

If you look a little bit further down in the Architecture TRM you will find this table which describes how each of the actual pins on the multiplexer work.

PSoC 6 Register TRM

If you want to start to make specific configurations for specific pins you will need to look into the PSoC 6 Register TRM.  In that document you will find that the

Register TRM

Register TRM

PSoC 6 Datasheet

But what are all of the active and deep sleep signals?  Well if you look in the PSoC 6 data sheet you can find all of those connections.  For instance on P0.1 active signal 8 is the SCB 0 SPI Select signal 2.

PSoC 6 PDL

But really all of these register reads and writes are not really that fun.  So, Cypress provides other, less painful ways of getting things going.  Specifically,

  • void Cy_GPIO_SetHSIOM(GPIO_PRT_Type* base, uint32_t pinNum, en_hsiom_sel_t value)

or

  • Cy_GPIO_Pin_Init(GPIO_PRT_Type *base, uint32_t pinNum, const cy_stc_gpio_pin_config_t *config)

When you call both of these function you need to provide the value for the multipler either directly in the Cy_GPIO_SetHSIOM or indirectly in the Cy_GPIO_Pin_Init case where you provide it as a member of the cy_stc_gpio_pin_config_t *config structure called “hsiom”

Depending on which package you have selected you will have a file like gpio_psoc6_01_124_bga.h which will have both the generic definitions for the HSIOM multiplexer select (like this)

/* HSIOM Connections */
typedef enum
{
/* Generic HSIOM connections */
HSIOM_SEL_GPIO                  =  0,       /* GPIO controls 'out' */
HSIOM_SEL_GPIO_DSI              =  1,       /* GPIO controls 'out', DSI controls 'output enable' */
HSIOM_SEL_DSI_DSI               =  2,       /* DSI controls 'out' and 'output enable' */
HSIOM_SEL_DSI_GPIO              =  3,       /* DSI controls 'out', GPIO controls 'output enable' */
HSIOM_SEL_AMUXA                 =  4,       /* Analog mux bus A */
HSIOM_SEL_AMUXB                 =  5,       /* Analog mux bus B */
HSIOM_SEL_AMUXA_DSI             =  6,       /* Analog mux bus A, DSI control */
HSIOM_SEL_AMUXB_DSI             =  7,       /* Analog mux bus B, DSI control */
HSIOM_SEL_ACT_0                 =  8,       /* Active functionality 0 */
HSIOM_SEL_ACT_1                 =  9,       /* Active functionality 1 */
HSIOM_SEL_ACT_2                 = 10,       /* Active functionality 2 */
HSIOM_SEL_ACT_3                 = 11,       /* Active functionality 3 */
HSIOM_SEL_DS_0                  = 12,       /* DeepSleep functionality 0 */
HSIOM_SEL_DS_1                  = 13,       /* DeepSleep functionality 1 */
HSIOM_SEL_DS_2                  = 14,       /* DeepSleep functionality 2 */
HSIOM_SEL_DS_3                  = 15,       /* DeepSleep functionality 3 */
HSIOM_SEL_ACT_4                 = 16,       /* Active functionality 4 */
HSIOM_SEL_ACT_5                 = 17,       /* Active functionality 5 */
HSIOM_SEL_ACT_6                 = 18,       /* Active functionality 6 */
HSIOM_SEL_ACT_7                 = 19,       /* Active functionality 7 */
HSIOM_SEL_ACT_8                 = 20,       /* Active functionality 8 */
HSIOM_SEL_ACT_9                 = 21,       /* Active functionality 9 */
HSIOM_SEL_ACT_10                = 22,       /* Active functionality 10 */
HSIOM_SEL_ACT_11                = 23,       /* Active functionality 11 */
HSIOM_SEL_ACT_12                = 24,       /* Active functionality 12 */
HSIOM_SEL_ACT_13                = 25,       /* Active functionality 13 */
HSIOM_SEL_ACT_14                = 26,       /* Active functionality 14 */
HSIOM_SEL_ACT_15                = 27,       /* Active functionality 15 */
HSIOM_SEL_DS_4                  = 28,       /* DeepSleep functionality 4 */
HSIOM_SEL_DS_5                  = 29,       /* DeepSleep functionality 5 */
HSIOM_SEL_DS_6                  = 30,       /* DeepSleep functionality 6 */
HSIOM_SEL_DS_7                  = 31,       /* DeepSleep functionality 7 */

As well as the pin by pin definitions… like this for P0_2

    /* P0.2 */
P0_2_GPIO                       =  0,       /* GPIO controls 'out' */
P0_2_AMUXA                      =  4,       /* Analog mux bus A */
P0_2_AMUXB                      =  5,       /* Analog mux bus B */
P0_2_AMUXA_DSI                  =  6,       /* Analog mux bus A, DSI control */
P0_2_AMUXB_DSI                  =  7,       /* Analog mux bus B, DSI control */
P0_2_TCPWM0_LINE1               =  8,       /* Digital Active - tcpwm[0].line[1]:0 */
P0_2_TCPWM1_LINE1               =  9,       /* Digital Active - tcpwm[1].line[1]:0 */
P0_2_CSD_CSD_TX                 = 10,       /* Digital Active - csd.csd_tx:2 */
P0_2_CSD_CSD_TX_N               = 11,       /* Digital Active - csd.csd_tx_n:2 */
P0_2_LCD_COM2                   = 12,       /* Digital Deep Sleep - lcd.com[2]:0 */
P0_2_LCD_SEG2                   = 13,       /* Digital Deep Sleep - lcd.seg[2]:0 */
P0_2_SCB0_UART_RX               = 18,       /* Digital Active - scb[0].uart_rx:0 */
P0_2_SCB0_I2C_SCL               = 19,       /* Digital Active - scb[0].i2c_scl:0 */
P0_2_SCB0_SPI_MOSI              = 20,       /* Digital Active - scb[0].spi_mosi:0 */

If you look at the Cy_GPIO_Pin_Init function you will see that on line 96 it sets the register which picks the correct pin mux.

cy_en_gpio_status_t Cy_GPIO_Pin_Init(GPIO_PRT_Type *base, uint32_t pinNum, const cy_stc_gpio_pin_config_t *config)
{
cy_en_gpio_status_t status = CY_GPIO_BAD_PARAM;
if ((NULL != base) && (NULL != config))
{
uint32_t maskCfgOut;
uint32_t tempReg;
CY_ASSERT_L2(CY_GPIO_IS_PIN_VALID(pinNum));
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->outVal));
CY_ASSERT_L2(CY_GPIO_IS_DM_VALID(config->driveMode));
CY_ASSERT_L2(CY_GPIO_IS_HSIOM_VALID(config->hsiom));  
CY_ASSERT_L2(CY_GPIO_IS_INT_EDGE_VALID(config->intEdge)); 
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->intMask));
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->vtrip));
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->slewRate));
CY_ASSERT_L2(CY_GPIO_IS_DRIVE_SEL_VALID(config->driveSel));
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->vregEn));
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->ibufMode));
CY_ASSERT_L2(CY_GPIO_IS_VALUE_VALID(config->vtripSel));
CY_ASSERT_L2(CY_GPIO_IS_VREF_SEL_VALID(config->vrefSel));
CY_ASSERT_L2(CY_GPIO_IS_VOH_SEL_VALID(config->vohSel));
Cy_GPIO_Write(base, pinNum, config->outVal);
Cy_GPIO_SetDrivemode(base, pinNum, config->driveMode);
Cy_GPIO_SetHSIOM(base, pinNum, config->hsiom);
Cy_GPIO_SetInterruptEdge(base, pinNum, config->intEdge);
Cy_GPIO_SetInterruptMask(base, pinNum, config->intMask);
Cy_GPIO_SetVtrip(base, pinNum, config->vtrip);
/* Slew rate and Driver strength */
maskCfgOut = (CY_GPIO_CFG_OUT_SLOW_MASK << pinNum) 
| (CY_GPIO_CFG_OUT_DRIVE_SEL_MASK << ((uint32_t)(pinNum << 1U) + CY_GPIO_CFG_OUT_DRIVE_OFFSET));
tempReg = GPIO_PRT_CFG_OUT(base) & ~(maskCfgOut);
GPIO_PRT_CFG_OUT(base) = tempReg | ((config->slewRate & CY_GPIO_CFG_OUT_SLOW_MASK) << pinNum)
| ((config->driveSel & CY_GPIO_CFG_OUT_DRIVE_SEL_MASK) << ((uint32_t)(pinNum << 1U) + CY_GPIO_CFG_OUT_DRIVE_OFFSET));
/* SIO specific configuration */
tempReg = GPIO_PRT_CFG_SIO(base) & ~(CY_GPIO_SIO_PIN_MASK);
GPIO_PRT_CFG_SIO(base) = tempReg | (((config->vregEn & CY_GPIO_VREG_EN_MASK)
| ((config->ibufMode & CY_GPIO_IBUF_MASK) << CY_GPIO_IBUF_SHIFT)
| ((config->vtripSel & CY_GPIO_VTRIP_SEL_MASK) << CY_GPIO_VTRIP_SEL_SHIFT)
| ((config->vrefSel & CY_GPIO_VREF_SEL_MASK)  << CY_GPIO_VREF_SEL_SHIFT)
| ((config->vohSel & CY_GPIO_VOH_SEL_MASK) << CY_GPIO_VOH_SEL_SHIFT))
<< ((pinNum & CY_GPIO_SIO_ODD_PIN_MASK) << CY_GPIO_CFG_SIO_OFFSET));
status = CY_GPIO_SUCCESS;
}
return(status);
}

And finally the Cy_GPIO_SetHSIOM actually writes to the register.

__STATIC_INLINE void Cy_GPIO_SetHSIOM(GPIO_PRT_Type* base, uint32_t pinNum, en_hsiom_sel_t value)
{
uint32_t portNum;
uint32_t tempReg;
HSIOM_PRT_V1_Type* portAddrHSIOM;
CY_ASSERT_L2(CY_GPIO_IS_PIN_VALID(pinNum));
CY_ASSERT_L2(CY_GPIO_IS_HSIOM_VALID(value));
portNum = ((uint32_t)(base) - CY_GPIO_BASE) / GPIO_PRT_SECTION_SIZE;
portAddrHSIOM = (HSIOM_PRT_V1_Type*)(CY_HSIOM_BASE + (HSIOM_PRT_SECTION_SIZE * portNum));
if(pinNum < CY_GPIO_PRT_HALF)
{
tempReg = HSIOM_PRT_PORT_SEL0(portAddrHSIOM) & ~(CY_GPIO_HSIOM_MASK << (pinNum << CY_GPIO_HSIOM_OFFSET));
HSIOM_PRT_PORT_SEL0(portAddrHSIOM) = tempReg | ((value & CY_GPIO_HSIOM_MASK) << (pinNum << CY_GPIO_HSIOM_OFFSET));
}
else
{
pinNum -= CY_GPIO_PRT_HALF;
tempReg = HSIOM_PRT_PORT_SEL1(portAddrHSIOM) & ~(CY_GPIO_HSIOM_MASK << (pinNum << CY_GPIO_HSIOM_OFFSET));
HSIOM_PRT_PORT_SEL1(portAddrHSIOM) = tempReg | ((value & CY_GPIO_HSIOM_MASK) << (pinNum << CY_GPIO_HSIOM_OFFSET));
}
}

PSoC 6 SPI

Finally, it may seem obvious, but there is a limited set of connections to each GPIO in PSoC 6.  This means that any given SCB can only connect its SPI pins to a specific set of pins on the chip.  But, what are they?  You can either look at the data sheet, or you can search the file which you will find the pin definitions which will all be in the form of Px_y_SCBz_SPI_MOSI and this will give you a complete map.

PSoC 6 SDK OneWire Bus (Part 4): But, Can It Read the Temperature?

Summary

In this series of articles I have been implementing a one-wire sensor library to work with PSoC 6.  In this article I will test the library by reading the temperature from the DS18B20 sensor.

Article
PSoC 6 SDK OneWire Bus (Part 1) : Build Basic Project
PSoC 6 SDK OneWire Bus (Part 2) : Implement Read & Write
PSoC 6 SDK OneWire Bus (Part 3) : Remove Busy Wait & Debug
PSoC 6 SDK OneWire Bus (Part 4): But, Can it Read the Temperature?
PSoC 6 SDK OneWire Bus (Part 5): Round out the OWB Driver

Story

After three articles crawling through one-wire documents and firmware we are down to the real question.  Will it actually read the temperature?  Each device on a one-wire bus is addressed by a unique 64-bit value which is programmed at the factory.  Before you can talk to a device you need to read the rom value.  The question is how do you find the ROM value when you have multiple devices connected on the bus?  There are two ways

  1. Follow a rather complicated discovery process (next article)
  2. If there is only 1 device on the bus you can follow a short cut.

Well, lets start with the simple method.

Read ROM

The data sheet is pretty clear about how to read the ROM code when you only have one device.  Basically, you send a 0x33, then you read 8 bytes.  Here is a clip from the data sheet.

I will add a command to my ntshell command line.  The command is “readrom” it will

  1. Send the reset
  2. Wait 1MS (I don’t think you have to do this, but this was a bug work around)
  3. Send the 0x33
  4. Then read 8 bytes.
  5. And print out the result (lines
OneWireBus_ROMCode rom;
static int usrcmd_readrom(int argc, char **argv)
{
owb_ret_t rval;
printf("Sending reset\n");
bool result;
rval = owb_reset(&bus,&result);
if(rval != OWB_STATUS_OK)
{
printf("Reset failed\n");
return 0;
}
CyDelay(1);
printf("Sending 0x33\n");
rval = owb_write_byte(&bus,0x33);
if(rval != OWB_STATUS_OK)
{
printf("Write 0x33 failed\n");
return 0;
}
// read 64-bit rom
printf("Reading 8 bytes\n");
rval = owb_read_bytes(&bus,rom.romAddr,8);
if(rval != OWB_STATUS_OK)
{
printf("read 8 bytes failed\n");
return 0;
}
// 
printf("Rom = ");
for(int i=0;i<8;i++)
{
printf("%02X ",rom.romAddr[i]);
}
printf("\n");
return 0;
}

When I test it, things seem to be working.

Read Temperature

Now that we know the ROM Code, which is used as the address, how do we get the temperature.  To do this you should follow this procedure.

  1. Do a Match ROM
  2. Send the ROM address
  3. Send a Convert Temperature
  4. Wait for the right amount of time
  5. Send a Read Scratch Pad
  6. Read 9 Bytes
  7. Convert the values

The Match ROM command 0x55 + the ROM code selects your device to be acted on.

When you send a convert T 0x44 your device will start the internal process of reading the temperature and storing it in the scratch pad.  The amount of time this take depends on what resolution you have configured.

The scratchpad is a 9-byte register inside of the chip which contains the most recently read temperature plus some settings.

To read the scratchpad you need to send a 0xBE, then read 9-bytes.  Notice that the 9th byte is a CRC for the first 8 bytes,  if you are concerned you can follow the CRC procedure documented in the datasheet to calculate a CRC to verify a match.  For this example, lets skip that.

In order to convert the temperature you need to know the resolution.  Bit-6 and Bit-5 of the configuration register tells you this.  This is a writable register so you can change the resolution which you might do to speed up the reading time.

Here is the whole code together as a new command.

static int usrcmd_readtemp(int argc, char **argv)
{
uint8_t scratchpad[9];
bool result;
// send reset
// send match rom 0x55
// send rom address
// send trigger 0x44
// delay 1 second
// send reset
// send match rom 0x55
// send read scratchpad BEh
// read 9 bytes of scratch pad
owb_reset(&bus,&result);
owb_write_byte(&bus,0x55);
owb_write_bytes(&bus,rom.romAddr,8);
owb_write_byte(&bus,0x44);
vTaskDelay(1000);
owb_reset(&bus,&result);
owb_write_byte(&bus,0x55);
owb_write_bytes(&bus,rom.romAddr,8);
owb_write_byte(&bus,0xbe);
owb_read_bytes(&bus,scratchpad,9);
printf("Scratchpad =");
for(int i=0;i<9;i++)
{
printf("%02X ",scratchpad[i]);
}
printf("\n");
int16_t tempbits = scratchpad[0] | (scratchpad[1] << 8);
uint32_t resolution=2^12;
float temperature=0.0;
switch(scratchpad[5] >>5 & 0x03)
{
case 0:
resolution = 2^9;
break;
case 1:
resolution = 2^10;
break;
case 2:
resolution = 2^11;
break;
case 3:
resolution = 2^12;
break;
}
temperature = (float)tempbits / (float)resolution;
printf("Temperature = %f\n",temperature);
return 0;  
}

Now I build and program the development kit to setup the test.  The first step is to read the ROM with the command line “readrom”.  Then I tell it to try to read the temperature.  You can see the values in the scratch pad, plus my conversion to celsius.  Since I am in Kentucky I probably should have done Fahrenheit … oh well. 28.35C is 83.3F my office is pretty hot today.

PSoC 6 SDK OneWire Bus (Part 3): Remove Busy Wait & Debug

Summary

In this article I will replace the stupid busy wait implementation of OneWire write and read bit with an interrupt based implementation.

Article
PSoC 6 SDK OneWire Bus (Part 1) : Build Basic Project
PSoC 6 SDK OneWire Bus (Part 2) : Implement Read & Write
PSoC 6 SDK OneWire Bus (Part 3) : Remove Busy Wait & Debug
PSoC 6 SDK OneWire Bus (Part 4): But, Can it Read the Temperature?
PSoC 6 SDK OneWire Bus (Part 5): Round out the OWB Driver

Story

In the previous article, I implemented a OneWire bus library for PSoC 6.  Specifically, to read temperatures from the DS18B20 1-wire temperature sensor.  This implementation used the CyDelay to handle bit timing. Here is the write bit function.

owb_ret_t owb_write_bit(OneWireBus *bus,uint8_t val)
{
owb_ret_t rval = OWB_STATUS_OK;
cyhal_gpio_write(bus->pin,0);
if(val == 0)
{
CyDelayUs(60);
cyhal_gpio_write(bus->pin,1);
CyDelayUs(2);
}
else
{
CyDelayUs(1);
cyhal_gpio_write(bus->pin,1);
CyDelayUs(60);
}
return rval;
}

And the read bit function.

owb_ret_t owb_read_bit( OneWireBus *bus, uint8_t *bit)
{
owb_ret_t rval = OWB_STATUS_OK;
cyhal_gpio_write(bus->pin,0);
CyDelayUs(1);
cyhal_gpio_write(bus->pin,1);
CyDelayUs(5);
*bit = cyhal_gpio_read(bus->pin);
CyDelayUs(60);
return rval;
}

Both of these functions APPEAR to work perfectly.  Here is a write of 0xFF

However, both of these implementations are subject to fail if an interrupt from the RTOS occurs during the delay period.  You could easily end up with a delay that is too long by enough that the sensor attached to the bus won’t work.  Moreover, I have always hated busy wait loops as the processor could be doing something useful.  So let’s replace this with something better.

This is a late edit to the article, but as I read the documentation for the “owb” library I found this note in Dave Antliff’s documentation

Im not exactly sure what a “RMT” is in the world of ESP32, but I gotta imagine that it is a hardware timer.

Implement an HW Timer and Interrupt Scheme

Both the read and write operation require that the master

  • Write a 0
  • Wait for some time
  • Write a 1
  • Wait for some time (then optionally read)
  • Wait for some time end

The PSoC 6 TCPWM can be used to generate accurate interrupts at specific times in the future.   This hardware is abstracted using the Cypress HAL which will let you configure

  • The input frequency to the timer
  • The counter in the timer
  • A “compare” value to trigger an interrupt with event type CYHAL_TIMER_IRQ_CAPTURE_COMPARE
  • A “period” value to trigger an interrupt with the event type CYHAL_TIMER_IRQ_TERMINAL_COUNT

If you are confused about the TCPWM hardware you are not alone, it can do a mind blowing amount of different things.  However in this simple case we have it set to

  1. Input frequency 1 Mhz (aka 1uS per count)
  2. Start at 0
  3. Trigger an event CYHAL_TIMER_IRQ_CAPTURE_COMPARE at the compare value
  4. Tigger an event CYHAL_TIMER_IRQ_TERMINAL_COUNT at the period
  5. Stop counting
  6. Reset back to 0

If you look the code below on lines 23-30 the configuration of the timer is set.  Remember from the data sheet that a “1” is a 1uS 0 followed by a 60uS 1 and a 0 is a 60uS 0 followed by a 1uS 1.  I use the “compare” to be the trigger from 0–>1.  Notice lines 5-9 in the code below.

On lines 40-41 I tell the HAL that I am interested in getting an event interrupt.

Line 43 initiates the write with a write of 0.  Then line 45 starts the timer going.

To “end” the operation I use a semaphore to wait until the interrupt is triggered by the Terminal Count (aka Period).

void write_bit_event_callback(void *callback_arg, cyhal_timer_event_t event)
{
OneWireBus *bus = (OneWireBus *)callback_arg;
if(event & CYHAL_TIMER_IRQ_CAPTURE_COMPARE)
{
cyhal_gpio_write(bus->pin,1);
}
if(event & CYHAL_TIMER_IRQ_TERMINAL_COUNT)
{
BaseType_t xHigherPriorityTaskWoken;
xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(bus->signalSemaphore,&xHigherPriorityTaskWoken);
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
}
owb_ret_t owb_write_bit(OneWireBus *bus,uint8_t val)
{
owb_ret_t rval;
cyhal_timer_cfg_t cfgBit = {
.is_continuous = false,
.direction = CYHAL_TIMER_DIR_UP,
.is_compare = true,
.compare_value = 1,
.period = 70,
.value = 0,
};
if(val == 0)
cfgBit.compare_value = 65;
else
cfgBit.compare_value = 1;
cyhal_timer_configure(&bus->bitTimer,&cfgBit);
cyhal_timer_reset(&bus->bitTimer);
cyhal_timer_register_callback(&bus->bitTimer,write_bit_event_callback,bus);
cyhal_timer_enable_event(&bus->bitTimer,CYHAL_TIMER_IRQ_TERMINAL_COUNT|CYHAL_TIMER_IRQ_CAPTURE_COMPARE,5,true);
cyhal_gpio_write(bus->pin,0);
cyhal_timer_start(&bus->bitTimer);
BaseType_t rsem = xSemaphoreTake(bus->signalSemaphore,1); 
if(rsem == pdTRUE)
rval = OWB_STATUS_OK;
else
rval = OWB_STATUS_ERROR;
return rval;
}

Fixing the Write Bug

When I programmed this code I got some weird stuff.  Suck.  So to debug it, I put in a command line to let me “wbyte ff” (or whatever byte value).  At the top of usrcmd.c you need to declare the usrcmd_wbyte function and add it to the command table (notice that I chopped out everything around it)

static int usrcmd_wbyte(int argc, char **argv);
static const cmd_table_t cmdlist[] = {
{ "wbyte","write byte", usrcmd_wbyte},
};

Then make a function will will take an argument (the value you want to write).  Notice that the input is a 2 digit hex number.  Yes I known sscanf is dangerous (but in this case I use it only as a debugging tool.)

static int usrcmd_wbyte(int argc, char **argv)
{
if(argc != 2)
{
printf("Invalid argument write  %d\n",argc);
return 0;
}
owb_ret_t ret=OWB_STATUS_OK;
int val;
sscanf(argv[1],"%02x",&val);
printf("Write Byte Val = %02X\n",val);
ret = owb_write_byte(&bus,(uint8_t)val);
if(ret == OWB_STATUS_OK)
printf("Write byte succeeded\n");
else
printf("Write byte failed\n");
return 0;
}

When I run the code I seem to get the write byte function working sometimes and failing sometimes.  What the hell?

Now, the pain starts.  To debug, I get out the oscilloscope and have a look.  Here is a write of 0xFF which should be 8 short 0 pulses.  But notice that only three get written.  OK, that must mean that the semaphore is timing out. How can that be?

To try to debug that I update a pin to toggle with the semaphore (and git rid of the exit case).

    cyhal_gpio_write(CYBSP_D5,1);
BaseType_t rsem = xSemaphoreTake(bus->signalSemaphore,1); 
cyhal_gpio_write(CYBSP_D5,0);

Now I get this (on the debug pin)… notice a very short timeout… then longer ones followed by another partially shorter timeout.

The problem is the semaphore timeout is set to 1.  Should be at least 1 ms right?  Why is that a problem as 1ms is way more than the 60-ish uS you need to wait?

BaseType_t rsem = xSemaphoreTake(bus->signalSemaphore,1);

Classic off by 1 error.  The 1 means expire at the NEXT SysTick, which will happen NO MORE than 1ms from now. Change it to 2.

    BaseType_t rsem = xSemaphoreTake(bus->signalSemaphore,2);

Now, all the bits come out at a steady rate.

And it works… sometimes…

Deep Sleep

Other times I end up with this picture.  Notice that the space between the start of one bit and the start of the next bit (from a-b on the scope) is 361.6 uS (don’t forget the 0.6 uS).

Why are the interrupts getting delayed?  The answer is the chip is in deep sleep (or going to deep sleep) when the interrupt from the timer happens.  And when the deep sleep is happening, it takes a bit of time to go to deep sleep, then to wake up.  To fix this go into the system configurator and change the Deep Sleep Latency.

Change the timeout to 3

Now it works.. here is a write of 0xFE

Implement the Read Bit

Now that the write bit is working, move the read bit function to the same scheme.  Notice that I use the compare to trigger the read of the pin.  In the read code I probably should have done a critical section from the start of the 0 to the start of the timer so that an interrupt doesn’t occur before the timer gets started.

void read_bit_event_callback(void *callback_arg, cyhal_timer_event_t event)
{
OneWireBus *bus = (OneWireBus *)callback_arg;
if(event & CYHAL_TIMER_IRQ_CAPTURE_COMPARE)
{
bus->scratchBitValue = cyhal_gpio_read(bus->pin);
}
if(event & CYHAL_TIMER_IRQ_TERMINAL_COUNT)
{
BaseType_t xHigherPriorityTaskWoken;
xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(bus->signalSemaphore,&xHigherPriorityTaskWoken);
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
}
owb_ret_t owb_read_bit( OneWireBus *bus, uint8_t *bit)
{
owb_ret_t rval;
cyhal_timer_cfg_t cfgBit = {
.is_continuous = false,
.direction = CYHAL_TIMER_DIR_UP,
.is_compare = true,
.compare_value = 10,
.period = 61,
.value = 0
};
cyhal_timer_configure(&bus->bitTimer,&cfgBit);
cyhal_timer_register_callback(&bus->bitTimer,read_bit_event_callback,bus);
cyhal_timer_enable_event(&bus->bitTimer,CYHAL_TIMER_IRQ_TERMINAL_COUNT|CYHAL_TIMER_IRQ_CAPTURE_COMPARE,5,true);
// Pull a 0
cyhal_gpio_write(bus->pin,0);
CyDelayUs(1);
cyhal_gpio_write(bus->pin,1);
cyhal_timer_reset(&bus->bitTimer);
cyhal_timer_start(&bus->bitTimer);
BaseType_t rsem = xSemaphoreTake(bus->signalSemaphore,2); // Then entire write cycle is 61uS so 2ms would be a major failure
*bit = bus->scratchBitValue;
if(rsem == pdTRUE)
rval = OWB_STATUS_OK;
else
rval = OWB_STATUS_ERROR;
return rval;
}

In fact as I look at this code, I decide that I had better to fix the critical section.  Here is the updated read code.

    void taskENTER_CRITICAL();
cyhal_gpio_write(bus->pin,0);     // Pull a 0
CyDelayUs(1);
cyhal_gpio_write(bus->pin,1);
cyhal_timer_start(&bus->bitTimer);
void taskEXIT_CRITICAL( );

And the updated write code

    taskENTER_CRITICAL();
cyhal_gpio_write(bus->pin,0);
cyhal_timer_start(&bus->bitTimer);
taskEXIT_CRITICAL();

In the next article I’ll show you code to actually read the temperature.

 

PSoC 6 SDK OneWire Bus (Part 2) : Implement Read & Write

Summary

In this article I will explain how to implement (badly) the one wire bus read & write functions using the PSoC 6 SDK.  This is one of many articles that are part of a series discussing the implementation:

Article
PSoC 6 SDK OneWire Bus (Part 1) : Build Basic Project
PSoC 6 SDK OneWire Bus (Part 2) : Implement Read & Write
PSoC 6 SDK OneWire Bus (Part 3) : Remove Busy Wait & Debug
PSoC 6 SDK OneWire Bus (Part 4): But, Can it Read the Temperature?
PSoC 6 SDK OneWire Bus (Part 5): Round out the OWB Driver

Story

In the previous article, I built a test framework inside of a PSoC 6 FreeRTOS project.  This includes a command line shell which will enable me to execute functions based on typed commands.  This means I can use the CLI shell to debug my interface.  To get going testing, I bought a DS18B20 temperature sensor from Mouser.

Then wired it like this:

Here is a picture of the test jig.  It looks like I used 4200 ohms instead of 4400 ohms, oh well it seems to work.

Init

Init seems like a good place to start.  To have a one wire bus you need to have a GPIO to read/drive.  So, that will be the only argument to the initialization function.  In the implementation I will use a common semaphore to handle blocking functions (line 13).  On lines 15-17 I initialize a timer to handle the requirements of reset, read and writes (more on this later).  At the end on line 20 I initialize the GPIO.

#include "owb.h"
#include <stdint.h>
#include "cyhal.h"
#include "cybsp.h"
#include "task.h"
#include <stdbool.h>
#include <stdio.h>
owb_ret_t owb_init(OneWireBus *bus)
{
cy_rslt_t rslt;
bus->signalSemaphore = xSemaphoreCreateBinary();
rslt = cyhal_timer_init(&bus->bitTimer,NC,0);
CY_ASSERT(rslt == CY_RSLT_SUCCESS);
rslt = cyhal_timer_set_frequency(&bus->bitTimer,1000000);
CY_ASSERT(rslt == CY_RSLT_SUCCESS);
rslt = cyhal_gpio_init(bus->pin,CYHAL_GPIO_DIR_BIDIRECTIONAL,CYHAL_GPIO_DRIVE_OPENDRAINDRIVESLOW,true);
CY_ASSERT(rslt == CY_RSLT_SUCCESS);
return OWB_STATUS_OK;    
}

In the usrcmd.c I need to add includes for the new stuff.

#include "cybsp.h"
#include "owb.h"

The next step is to add the “init” command to usrcmd.c  This is accomplished by adding a function header for usrcmd_init and adding it to the table of legal commands.

static int usrcmd_init(int argc, char **argv);
typedef struct {
char *cmd;
char *desc;
USRCMDFUNC func;
} cmd_table_t;
static const cmd_table_t cmdlist[] = {
{ "help", "This is a description text string for help command.", usrcmd_help },
{ "info", "This is a description text string for info command.", usrcmd_info },
{ "clear", "Clear the screen", usrcmd_clear },
{ "printargs","print the list of arguments", usrcmd_printargs},
{ "init","Initialize the 1-wire bus", usrcmd_init},
};

Then you need to add the usrcmd_init function to call the owb init.

static OneWireBus bus;
static int usrcmd_init(int argc, char **argv)
{
bus.pin = CYBSP_D4;
owb_init(&bus);
printf("Initialized D4\n");
return 0;
}

Now test it.  All good.

Reset

In order to reset the bus you follow this process

  1. Pull down the bus for trstl=480uS
  2. Let the bus go back to 1 (remember that it is restive pull-up)
  3. Wait another trsth=480uS
  4. If there is a slave device on the bus it will pull down the bus at some point to indicate a “presence detect”

From the data sheet you can see that the low& high times = 480uS.  At some point during the high period the slave will pull the bus down for 15->60uS

In order to implement the reset I will modify the owb.c file.  To meet the timing requirements I will use a cyhal_timer.  The cyhal_timer is implemented in the Cypress PDL at a Cy_TCPWM_Timer which is then implemented in the hardware as a timer counter.  In this configuration the timer has:

  • A Counter (an up or down counter)
  • A Compare (a register which can be compared with the counter to trigger events)
  • A Period (a register which is compared to the counter to reset the counter back to 0).   This event is also called the “terminal count”

For this implementation I will setup a timer with

  1. Input clock 1Mz (aka 1uS per count)
  2. An up counter
  3. Starts at 0
  4. Compare value = 480 (means trigger an interrupt at 480uS)
  5. Period = 960 (means trigger an interrupt at 480uS)
  6. One shot (stop counting when you get to period (aka Terminal Count))

The code will

  1. Configure the timer (line 41-52)
  2. Pull a 0 onto the bus (line 54)
  3. Start the timer (line 56)
  4. At the compare value 480uS reset the bus to 1 using the event handler (line 20) and setup the GPIO trigger a fall event interrupt (line 21-22)
  5. At the period release the semaphore (27-30)
  6. After the compare value if the GPIO pulls down, use the GPIO interrupt to record the presence of a device (line 10)
/////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Reset
/////////////////////////////////////////////////////////////////////////////////////////////////////////////
static void reset_gpio_event_callback(void *callback_arg, cyhal_gpio_event_t event)
{
OneWireBus *bus = (OneWireBus *)callback_arg;
if(event & CYHAL_GPIO_IRQ_FALL)
{
bus->detect = true;
}
}
static void reset_timer_event_callback(void *callback_arg, cyhal_timer_event_t event)
{
OneWireBus *bus = (OneWireBus *)callback_arg;
if(event & CYHAL_TIMER_IRQ_CAPTURE_COMPARE)
{
cyhal_gpio_write(bus->pin,1);
cyhal_gpio_register_callback(bus->pin, reset_gpio_event_callback,(void *)bus);
cyhal_gpio_enable_event(bus->pin,CYHAL_GPIO_IRQ_FALL,5,true);
}
if(event & CYHAL_TIMER_IRQ_TERMINAL_COUNT)
{
BaseType_t xHigherPriorityTaskWoken;
xHigherPriorityTaskWoken = pdFALSE;
xSemaphoreGiveFromISR(bus->signalSemaphore,&xHigherPriorityTaskWoken);
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
}
owb_ret_t owb_reset(OneWireBus *bus, bool *result)
{
owb_ret_t rval = OWB_STATUS_OK;
bus->detect = false;
cyhal_timer_cfg_t cfgBit = {
.is_continuous = false,
.direction = CYHAL_TIMER_DIR_UP,
.is_compare = true,
.compare_value = 480,
.period = 960,
.value = 0
};
cyhal_timer_configure(&bus->bitTimer,&cfgBit);
cyhal_timer_reset(&bus->bitTimer);
cyhal_timer_register_callback(&bus->bitTimer,reset_timer_event_callback,bus); 
cyhal_timer_enable_event(&bus->bitTimer,CYHAL_TIMER_IRQ_ALL,5,true);
cyhal_gpio_write(bus->pin,0);
cyhal_timer_start(&bus->bitTimer);
xSemaphoreTake(bus->signalSemaphore,2); // worst case is really 960uS
cyhal_gpio_enable_event(bus->pin,CYHAL_GPIO_IRQ_FALL,5,true);
return rval;
}

Once I have the owb_init code I add the init command to usrcmd.c.

static int usrcmd_reset(int argc, char **argv)
{
bool result;
owb_reset(&bus,&result);
if(bus.detect)
{
printf("Reset Succeeded\n");
}
else
printf("Reset Failed\n");
return 0;
}

When I run it, I get this nice picture from the oscilliscope.

Write

In the ds18b20.c file I see that the author has three functions of interest.  In the implementation owb_write_bytes will call owb_write byte and owb_write_byte will call owb_write bit.

owb_ret_t owb_write_bit( OneWireBus *bus, uint8_t val);
owb_ret_t owb_write_byte( OneWireBus *bus, uint8_t val);
owb_ret_t owb_write_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length);

The one wire protocol has the following steps.

In order to write a “0” you need to

  1. Pull down the bus (write a 0)
  2. Wait 60uS
  3. Write a 1
  4. Wait 1uS (to allow the next “slot” to start

In order to write a “1” you need to

  1. Pull down the bus (write a 0)
  2. Wait 1 uS
  3. Write a 1
  4. Wait 60uS (to allow the next “slot” to start)

Notice that the minimum write slot is 60uS and the maximum is 120uS.  Here is a picture from the data sheet.

For the first implementation of owb_write_bit I will use a simple “CyDelayUs”  to implement the delays (this is a bad idea, but is a ‘cheap’ way to get going).

owb_ret_t owb_write_bit(OneWireBus *bus,uint8_t val)
{
owb_ret_t rval = OWB_STATUS_OK;
cyhal_gpio_write(bus->pin,0);
if(val == 0)
{
CyDelayUs(60);
cyhal_gpio_write(bus->pin,1);
CyDelayUs(2);
}
else
{
CyDelayUs(1);
cyhal_gpio_write(bus->pin,1);
CyDelayUs(60);
}
return rval;
}

The write byte function just loops through the 8-bit and uses the owb_write_bit function.  Notice that it is least significant bit first.

owb_ret_t owb_write_byte( OneWireBus *bus, uint8_t val)
{
owb_ret_t ret = OWB_STATUS_OK;
for(int i=0;i<8;i++)
{
ret = owb_write_bit(bus,(val>>i) & 0x01);
if(ret != OWB_STATUS_OK)
return ret;        
}
return OWB_STATUS_OK;
}

And write_bytes (multiple) just loops through the buffer calling the write_byte function.

owb_ret_t owb_write_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length)
{
owb_ret_t ret = OWB_STATUS_OK;
for(int i=0;i<length;i++)
{
ret = owb_write_byte(bus,buffer[i]);
if(ret != OWB_STATUS_OK)
return ret;
}
return OWB_STATUS_OK;
}

Now that I have the three write functions I will add a new command to usrcmd.c  This function lets the user type a command like “wbyte a1” where he/she can input a 2-character hex command.  Yes, I use the sscanf function which is unsafe… but cheap for a test rig.

static int usrcmd_wbyte(int argc, char **argv)
{
if(argc != 2)
{
printf("Invalid argument write  %d\n",argc);
return 0;
}
owb_ret_t ret=OWB_STATUS_OK;
int val;
sscanf(argv[1],"%02x",&val);
printf("Write Byte Val = %02X\n",val);
ret = owb_write_byte(&bus,(uint8_t)val);
if(ret == OWB_STATUS_OK)
printf("Write byte succeeded\n");
else
printf("Write byte failed\n");
return 0;
}

When I program and launch the project I end up here.

OK that is easy enough to fix, I just ran out of stack in the ntshell thread.

    xTaskCreate(ntShellTask, "nt shell task", configMINIMAL_STACK_SIZE*3,0 /* args */ ,0 /* priority */, 0);

Now when I run it I am off to the races.

Here is an example of “wbyte ff”

What about “owb_write_rom_code”?  I don’t know what it does, but Ill figure it out as I integrate the rest of the library.

Read

When I examine the ds18b20.c file I find these three read functions, which mirror the write functions.

owb_ret_t owb_read_bit( OneWireBus *bus, uint8_t *bit);
owb_ret_t owb_read_byte( OneWireBus *bus, uint8_t *byte);
owb_ret_t owb_read_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length);

To read a bit you follow a a very similar process to the write.

  1. Write a 0 on the bus
  2. Wait 1uS
  3. Write a 1 on the bus (release the bus)
  4. Wait 5uS
  5. Read (the slave will pull a 0 or a 1 onto the bus)
  6. Wait 55uS to the end of the slot

Here is a picture

The code uses a really bad busy-wait delay (but it is a good starting place to figure out what is happening)

owb_ret_t owb_read_bit( OneWireBus *bus, uint8_t *bit)
{
owb_ret_t rval = OWB_STATUS_OK;
cyhal_gpio_write(bus->pin,0);
CyDelayUs(1);
cyhal_gpio_write(bus->pin,1);
CyDelayUs(5);
*bit = cyhal_gpio_read(bus->pin);
CyDelayUs(55);
return rval;
}

To read a byte, just read 8 bits using the owb_read_bit function

owb_ret_t owb_read_byte( OneWireBus *bus, uint8_t *byte)
{
uint8_t bit;
owb_ret_t ret = OWB_STATUS_OK;
*byte = 0;
for(int i=0;i<8;i++)
{
ret = owb_read_bit(bus,&bit);
if(ret != OWB_STATUS_OK)
return ret;
*byte = *byte | (bit<<i);
}
return OWB_STATUS_OK;
}

To read an array of bytes, use a loop of read_byte

owb_ret_t owb_read_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t count)
{
owb_ret_t ret = OWB_STATUS_OK;
for(int i=0;i<count;i++)
{
ret = owb_read_byte(bus,&buffer[i]);
if(ret != OWB_STATUS_OK)
return ret;       
}
return ret;
}

Now that you have a read and a write, update the usrcmd.c to add a “rbyte” command to the CLI

static int usrcmd_rbyte(int argc, char **argv)
{
owb_ret_t ret=OWB_STATUS_OK;
uint8_t val;
ret = owb_read_byte(&bus,&val);
if(ret == OWB_STATUS_OK)
printf("Read byte succeeded %02x\n",val);
else
printf("Read byte failed\n");
return 0;
}

When I program the kit I can send a 0x33 (which will make the sensor respond more on this later), then read the first byte of the ROM

When you look at the scope picture (from right to left) you can see 10110110 which sure enough is B6.  The thin gaps are 1’s and the wide gaps are 0’s

In the next article Ill deal with the stupid CyDelay’s

PSoC 6 SDK OneWire Bus (Part 1) : Build Basic Project

Summary

This is the first article in a series about my journey implementing PSoC 6 SDK libraries for the Maxxim One Wire Bus and the DS18B20 temperature sensor.

As you can see there will be many parts to this story:

Article
PSoC 6 SDK OneWire Bus (Part 1) : Build Basic Project
PSoC 6 SDK OneWire Bus (Part 2) : Implement Read & Write
PSoC 6 SDK OneWire Bus (Part 3) : Remove Busy Wait & Debug
PSoC 6 SDK OneWire Bus (Part 4): But, Can it Read the Temperature?
PSoC 6 SDK OneWire Bus (Part 5): Round out the OWB Driver

Story

I recently got a twitter message from a gentleman named “Neeraj Dhekale”.  He asked about a library for a one wire sensor for PSoC, actually to be specific he asked about a component for a PSoC 4.

Then I asked him what sensor and responded that he wanted to use the Maxxim DS18B20 temperature sensor.

This sensor is a one wire temperature sensor, here is a bit of snapshot from the data sheet.

After reading the data sheet I decided that I really didn’t want to implement a complete library for this sensor.  So, I started looking around for a driver library.  After googling around a little bit I found a library on GitHub (https://github.com/DavidAntliff/esp32-ds18b20) which looked promising, even though it is ESP32 specific.

But, after looking at this GitHub library a bit, I decide to start from there.

Before I get started two comments.

  1. He asked for PSoC 4 … but I am going to do PSoC 6 (because I can use Modus Toolbox).  There is no reason why this wouldn’t work on PSoC 4 – but it would take a bit of work
  2. I can’t think of a good reason to use 1-wire, it sure seems like I2C would be simpler

Build a Base Project

I start this whole effort by creating a new project for the CY8CKIT-062S2-43012 (because that happens to be the kit on my desk at the moment)

I will use the IoT Expert FreeRTOS Template project

For debugging this whole thing I will use a command line shell.  To get this into the project I add the ntshell library. Run “make modlibs” to start the library manager.

In the library manager pick the “ntshell” library

To develop this project I want to use Visual Studio code.  So, I run “make vscode” (to create the configuration files) and start vscode by running “code .”

When VSCODE starts up it looks like this:

In order to use the ntshell library you need to shuffle the files around a little bit.  Move the ntshell.h/.c into the main project by doing a drag/drop in the explorer window.

It will ask you really want to move the files

Once it is done, the ntshell functions which you need to customize will be part of the project.

To use the ntshell, you need to add the task to main.c

#include "cy_pdl.h"
#include "cyhal.h"
#include "cybsp.h"
#include "cy_retarget_io.h"
#include <stdio.h>
#include "FreeRTOS.h"
#include "task.h"
#include "ntshell.h"
#include "ntlibc.h"
#include "psoc6_ntshell_port.h"
// Global variable with a handle to the shell
ntshell_t ntshell;
void ntShellTask()
{
printf("Started ntshell\n");
setvbuf(stdin, NULL, _IONBF, 0);
ntshell_init(
&ntshell,
ntshell_read,
ntshell_write,
ntshell_callback,
(void *)&ntshell);
ntshell_set_prompt(&ntshell, "DS18B20> ");
vtsend_erase_display(&ntshell.vtsend);
ntshell_execute(&ntshell);
}

And start the task

    xTaskCreate(ntShellTask, "nt shell task", configMINIMAL_STACK_SIZE*2,0 /* args */ ,0 /* priority */, 0);

Build and compile

And you should have a working project.

Run “make program” to get the board going

arh (master *) OWB_DS18B20 $ make program
Tools Directory: /Applications/ModusToolbox/tools_2.1
Prebuild operations complete
Commencing build operations...
Tools Directory: /Applications/ModusToolbox/tools_2.1
Initializing build: mtb-example-psoc6-empty-app Debug CY8CKIT-062S2-43012 GCC_ARM
Auto-discovery in progress...
-> Found 202 .c file(s)
-> Found 50 .S file(s)
-> Found 27 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 4 .a file(s)
-> Found 450 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete
Constructing build rules...
Build rules construction complete
==============================================================================
= Building application =
==============================================================================
Building 181 file(s)
==============================================================================
= Build complete =
==============================================================================
Calculating memory consumption: CY8C624ABZI-D44 GCC_ARM -Og
---------------------------------------------------- 
| Section Name         |  Address      |  Size       | 
---------------------------------------------------- 
| .cy_m0p_image        |  0x10000000   |  5972       | 
| .text                |  0x10002000   |  49532      | 
| .ARM.exidx           |  0x1000e17c   |  8          | 
| .copy.table          |  0x1000e184   |  24         | 
| .zero.table          |  0x1000e19c   |  8          | 
| .data                |  0x080022e0   |  1688       | 
| .cy_sharedmem        |  0x08002978   |  8          | 
| .noinit              |  0x08002980   |  148        | 
| .bss                 |  0x08002a14   |  985176     | 
| .heap                |  0x080f3270   |  46480      | 
---------------------------------------------------- 
Total Internal Flash (Available)          2097152    
Total Internal Flash (Utilized)           59468      
Total Internal SRAM (Available)           1046528    
Total Internal SRAM (Utilized)            1033500    
Programming target device... 
Open On-Chip Debugger 0.10.0+dev-3.0.0.665 (2020-03-20-17:12)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
adapter speed: 2000 kHz
** Auto-acquire enabled, use "set ENABLE_ACQUIRE 0" to disable
cortex_m reset_config sysresetreq
cortex_m reset_config sysresetreq
Info : Using CMSIS loader 'CY8C6xxA_SMIF' for bank 'psoc6_smif0_cm0' (footprint 6485 bytes)
Warn : SFlash programming allowed for regions: USER, TOC, KEY
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : KitProg3: FW version: 1.11.159
Info : KitProg3: Pipelined transfers disabled, please update the firmware
Warn : *******************************************************************************************
Warn : * KitProg firmware is out of date, please update to the latest version using fw-loader at *
Warn : * ModusToolbox/tools/fw-loader                                                            *
Warn : *******************************************************************************************
Info : VTarget = 3.263 V
Info : kitprog3: acquiring PSoC device...
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x6ba02477
Info : psoc6.cpu.cm0: hardware has 4 breakpoints, 2 watchpoints
Info : psoc6.cpu.cm0: external reset detected
***************************************
** Silicon: 0xE402, Family: 0x102, Rev.: 0x11 (A0)
** Detected Device: CY8C624ABZI-S2D44A0
** Detected Main Flash size, kb: 2048
** Flash Boot version: 3.1.0.45
** Chip Protection: NORMAL
***************************************
Info : psoc6.cpu.cm4: hardware has 6 breakpoints, 4 watchpoints
Info : psoc6.cpu.cm4: external reset detected
Info : Listening on port 3333 for gdb connections
Info : Listening on port 3334 for gdb connections
Info : kitprog3: acquiring PSoC device...
target halted due to debug-request, current mode: Thread 
xPSR: 0x41000000 pc: 0x00000190 msp: 0x080ff800
** Device acquired successfully
** psoc6.cpu.cm4: Ran after reset and before halt...
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x0000012a msp: 0x080ff800
** Programming Started **
auto erase enabled
Info : Flash write discontinued at 0x10001754, next section at 0x10002000
Info : Padding image section 0 at 0x10001754 with 172 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
Info : Padding image section 1 at 0x1000e844 with 444 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
wrote 57856 bytes from file /Users/arh/proj/xxx/OWB_DS18B20/build/CY8CKIT-062S2-43012/Debug/mtb-example-psoc6-empty-app.hex in 2.294771s (24.621 KiB/s)
** Programming Finished **
** Verify Started **
verified 57240 bytes in 0.155447s (359.598 KiB/s)
** Verified OK **
** Resetting Target **
shutdown command invoked
arh (master *) OWB_DS18B20 $

And you should have a working project (with a blinking led and a command line)

Add the DS18B20 Library

Now that I have a working project the next step is to clone the DS18B20 library into my project.  This is done using

  • git clone https://github.com/DavidAntliff/esp32-ds18b20

The next step is to establish how bad things are with the new library.  So run the compiler.

When I look at the ds18b20.c file I can see that there are some obvious problems

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "esp_system.h"
#include "esp_log.h"
#include "ds18b20.h"
#include "owb.h"

Fix those:

#include "FreeRTOS.h"
#include "task.h"
//#include "driver/gpio.h"
//#include "esp_system.h"
//#include "esp_log.h"
#include "ds18b20.h"
//#include "owb.h"

Run the compiler again.  Now I am missing owb.h which is the public header file for the one wire bus.

In file included from esp32-ds18b20/ds18b20.c:47:0:
./esp32-ds18b20/include/ds18b20.h:37:10: fatal error: owb.h: No such file or directory
#include "owb.h"

I now make a directory to hold the new owb files called “p6sdk-onewire”.  Then I add a file “owb.h” (as a blank file)

When I run the compiler again, there are now two classes or error … owb and esp32 logging function. Here is an example of the ESP_ problems.

esp32-ds18b20/ds18b20.c:249:17: warning: implicit declaration of function 'ESP_LOG_BUFFER_HEX_LEVEL' [-Wimplicit-function-declaration]
ESP_LOG_BUFFER_HEX_LEVEL(TAG, scratchpad, count, ESP_LOG_DEBUG);
^~~~~~~~~~~~~~~~~~~~~~~~
esp32-ds18b20/ds18b20.c:249:66: error: 'ESP_LOG_DEBUG' undeclared (first use in this function)
ESP_LOG_BUFFER_HEX_LEVEL(TAG, scratchpad, count, ESP_LOG_DEBUG);

And here is an example of the owb problems.

esp32-ds18b20/ds18b20.c: In function 'ds18b20_wait_for_conversion':
esp32-ds18b20/ds18b20.c:504:30: error: request for member 'use_parasitic_power' in something not a structure or union
if (ds18b20_info->bus->use_parasitic_power)
^~
esp32-ds18b20/ds18b20.c: At top level:
esp32-ds18b20/ds18b20.c:568:54: error: unknown type name 'OneWireBus'
DS18B20_ERROR ds18b20_check_for_parasite_power(const OneWireBus * bus, bool * present)
^~~~~~~~~~
esp32-ds18b20/ds18b20.c: In function 'ds18b20_check_for_parasite_power':
esp32-ds18b20/ds18b20.c:577:44: error: 'OWB_ROM_SKIP' undeclared (first use in this function); did you mean 'CY_ROM_SIZE'?
if ((err = owb_write_byte(bus, OWB_ROM_SKIP)) == DS18B20_OK)
^~~~~~~~~~~~
CY_ROM_SIZE
make[1]: *** [/Users/arh/proj/xxx/OWB_DS18B20/build/CY8CKIT-062S2-4301

To make this thing go, I edit ds18b20.c file and add logging templates (just stub functions that don’t do anything)

void ESP_LOGD(const char * code, char *val,...)
{
}
void ESP_LOGE(const char * code, ...)
{
}
void ESP_LOGW(const char *code,...)
{
}
#define ESP_LOG_DEBUG 0
void ESP_LOG_BUFFER_HEX_LEVEL(const char *code,...)
{
}
uint64_t esp_timer_get_time()
{
return 0;
}

Create owb.h

If I was smart, I would have started with David Antliff “owb” library.  But I don’t.  What I do is search through “ds18b20.c” and find every function call to owb_ and then copy those function calls into owb.h (my new file).  Then I fix the function calls to have correct prototypes based on what I see in the ds18b20 library.  Here is what my owb.h file looks like after that process.

#ifndef OWB_H
#define OWB_H
#ifdef __cplusplus
extern "C" {
#endif
#define OWB_ROM_MATCH 0
#define OWB_ROM_SKIP 0
#include <stdint.h>
#include "cyhal.h"
#include "FreeRTOS.h"
#include "semphr.h"
typedef struct  
{
cyhal_gpio_t  pin;
bool use_parasitic_power;
SemaphoreHandle_t signalSemaphore;
cyhal_timer_t bitTimer;
bool detect;
SemaphoreHandle_t owb_num_active;
} OneWireBus;        
typedef struct {
uint8_t romAddr[8];
} OneWireBus_ROMCode;
typedef enum {
OWB_STATUS_OK,
OWB_STATUS_ERROR,
} owb_ret_t ;
owb_ret_t owb_init(OneWireBus *bus);
owb_ret_t owb_reset(OneWireBus *bus, bool *result);
owb_ret_t owb_write_bit( OneWireBus *bus, uint8_t val);
owb_ret_t owb_write_byte( OneWireBus *bus, uint8_t val);
owb_ret_t owb_write_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length);
owb_ret_t owb_write_rom_code(OneWireBus *bus, OneWireBus_ROMCode romcode);
owb_ret_t owb_read_bit( OneWireBus *bus, uint8_t *bit);
owb_ret_t owb_read_byte( OneWireBus *bus, uint8_t *byte);
owb_ret_t owb_read_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length);
owb_ret_t owb_crc8_bytes(uint32_t val, uint8_t *buffer, uint32_t length);
void   owb_set_strong_pullup( OneWireBus *bus, bool val);
#endif
#ifdef __cplusplus
}
#endif

When I run the compiler again things look way better (just some complaining about const datatypes) and a complaint about the include path.  The include path thing is visual studio code not knowing that I added a new directory called p6sdk-onewire.

To fix the include path I run “make vscode” which tells VSCODE about the new directory.

That is a good place to split this article.  In the next article I will add functions to read and write the bus.

PSoC 6 TCPWM Pulse Width Measurement

Summary

This article walks you through a PSoC 6 SDK example of measuring a pulse width using the TCPWM block’s counter function.

The Story

Recently I have been working with a Cypress guy and frequent collaborator Hassane.  He is working on a project that includes some kind of sonic distance sensor (I am actually not sure which one).  In order to “read” the sensor you need to be able to measure the width of a pulse which is easy enough to do using the TCPWM.  I originally wanted to use the Cypress HAL to setup the PSoC 6 to do this function, but it is not yet enabled.  So, I need to use PDL and the PSoC 6 Configurator.

Configure The TCPWM

Start with a new PSoC 6 project.  In my case I am using the CY8CKIT-062-WiFi-BT development kit because I had one where I had already soldered a wire onto the user switch.  My plan is to create a “pulse” with the user switch, starting from the press, ending with the user letting go.  This will be an active low pulse.  I will configure the TCPWM to have start, reload setup as Falling edges.  In other words the counter will reset and start counting when the button is pressed.  Then I will setup Stop and Reload on Rising edges, in other words the timer will STOP and give an interrupt on the rising edge.  All of these pins are connected to P9[0] on the PSoC.

You might ask yourself, why P9[0]?  That development kit has a switch connected to P0[4] seems like you should have connected the TCPWM to that pin.  That was done because the TCPWM is only attached to a limited set of signals.  Here is a screenshot from the configurator.

I want this setup to be interrupt based, specifically I want an interrupt when the Capture signal is active.  It is also interesting when the counter rolls over (overflow).  So I setup the interrupt source to be “Overflow & Underflow or Compare & Capture”.

The last thing you need is a clock.   you now need a clock.  To do this clock on the Clock Signal.  For this example I decided to use a 16-bit clock.

But what frequency is the input clock?  To set this go to the “Peripheral-Clocks”  The click on the divider you choose from above.  Then pick a divide value.  I choose 10000 which will give me 100MHz/10K=10KHz.

But where did the 100MHz come from?  Click on the “System” and look at the clock diagram.  All of the “Peripheral Clocks” use the signal “CLK_PERI” as their source.  This is attached to CLK_HF0 (which is 100Mhz) in this case.

The Program

Once is everything is configured you need to write a bit of code.

9-14: First I create an ISR which will set a flag and clear the interrupt source in the TCPWM

Then I write a main function

20: Turn on the printf functionality using the cy_retarget_io library

25: Initialize the counter using the structure created by the configurator.

26: Then I enable the counter to run.  Be careful with this function because counter numbers are NOT the same thing as counter masks.  Counter 3 is counter mask 1<<3=8

28-30: Turn on the interrupts and register my ISR called counterDone

34: In the loop I wait around until the flag gets set by the ISR

36: Read the value from the counter and convert it to seconds

37: Print the value

38: Reset the flag

And do it all over again

#include "cy_pdl.h"
#include "cyhal.h"
#include "cybsp.h"
#include "cy_retarget_io.h"
#include <stdio.h>
volatile int flag=0;
void counterDone()
{
uint32 intCause = Cy_TCPWM_GetInterruptStatusMasked(MYC_HW,MYC_NUM);
flag = 1;
Cy_TCPWM_ClearInterrupt(MYC_HW,MYC_NUM,intCause);
}
int main(void)
{
cybsp_init() ;
cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);
__enable_irq();
printf("Started\n");
Cy_TCPWM_Counter_Init(MYC_HW,MYC_NUM,&MYC_config);
Cy_TCPWM_Enable_Multiple(MYC_HW,MYC_MASK);
cy_stc_sysint_t mycounter= {.intrSrc = MYC_IRQ, .intrPriority=7};
Cy_SysInt_Init(&mycounter,counterDone);
NVIC_EnableIRQ(MYC_IRQ);
for(;;)
{
if(flag == 1)
{
float val = (float)Cy_TCPWM_Counter_GetCounter(MYC_HW,MYC_NUM) / 10000.0;
printf("%.2fs\n",val);
flag = 0;
}
}
}

Test

For an earlier article I had to solder a wire onto the switch.  This let me attach it to an oscilliscope.  It turns out that was an easy way to attach the switch to P9[0]

When I run the project I get a bunch of different pulse.  Looks good.