Feature/hal/nfc

[YutingYou]

Problem

Implement NFC Type 2 HAL driver

NOTE: This PR changed the timer used by USART, because NFC uses timer 4. Now we use timer 1 in USART driver.

Steps to Test

1. Flash example application to Xenon
2. Connect NFC antenna to Xenon
3. Use mobile phone NFC app to scan NFC antenna
4. When connected, D7 LED will turn on and you'll see the Particle website on your phone NFC app

Example App

#include "application.h"
#include "nfc_hal.h"
#include "nfc_ndef_msg.h"
#include "nfc_text_rec.h"
#include "nfc_uri_msg.h"
#include "nfc_t2t_lib.h"

SYSTEM_MODE(MANUAL);

static void nfc_event_callback(nfc_event_type_t type, nfc_event_t *event, void *ctx) {
    switch (type) {
        case NFC_EVENT_FIELD_ON: {
            digitalWrite(D7, 1);
            break;
        }
        case NFC_EVENT_FIELD_OFF: {
            digitalWrite(D7, 0);
            break;
        }
        case NFC_EVENT_READ: {
            break;
        }
        default:
            break;
    }
}

void setup(void) {
    static const uint8_t m_url[] = {'p', 'a', 'r', 't', 'i', 'c', 'l', 'e', '.', 'i', 'o'}; //URL "particle.com"
    static uint8_t m_ndef_msg_buf[256];

    // Just for NFC HAL API test, encode work will be done in wiring API
    uint32_t len = sizeof(m_ndef_msg_buf);
    uint32_t err_code = nfc_uri_msg_encode( NFC_URI_HTTP_WWW, m_url, sizeof(m_url), m_ndef_msg_buf, &len);
    APP_ERROR_CHECK(err_code);

    pinMode(D7, OUTPUT);
    digitalWrite(D7, 0);
    hal_nfc_type2_init();
    hal_nfc_type2_set_callback(nfc_event_callback);
    hal_nfc_type2_set_payload(m_ndef_msg_buf, len);
    hal_nfc_type2_start_emulation();
}

void loop() {

}

Update

NFC Wiring API Test

1. Flash Example App
2. Use NFC Reader application on iOS to scan NFC Tag, you'll see three record
3. Click mode button, NFC records are updated

Example App

void nfc_event_handler(nfc_event_type_t type, nfc_event_t *event, void* ctx) {
    switch (type) {
        case NFC_EVENT_FIELD_ON:  digitalWrite(D7, 1); break;
        case NFC_EVENT_FIELD_OFF: digitalWrite(D7, 0); break;
        case NFC_EVENT_READ:      digitalWrite(D7, 0); break;
        default: break;
    }
}

void setup() {
    pinMode(D7, OUTPUT);
    digitalWrite(D7, 0);

    System.on(button_click, [](system_event_t ev, int clicks)->void {
        NFC.getNdefMessage()[0] = std::make_shared<TextRecord>("Update record - 1!", "en");
        NFC.getNdefMessage()[1] = std::make_shared<TextRecord>("Update record - 2!", "en");
        NFC.getNdefMessage()[2] = std::make_shared<TextRecord>("Update record - 3!", "en");
        NFC.getNdefMessage().addTextRecord("New record!", "en");

        NFC.stop();
        NFC.start(nfc_event_handler);
    });

    NFC.getNdefMessage().addTextRecord("Hello Particle!", "en");
    NFC.getNdefMessage().addUriRecord("particle.io", UriRecord::NFC_URI_HTTPS_WWW);
    NFC.getNdefMessage().addLauchAppRecord("io.particle.android.app");

    NFC.start(nfc_event_handler);
}

void loop() {

}

Note

1. UID setting is not supported by Nordic Library, will be supported in the future
2. Lauch app only supports Android platform
3. TODO: Only support one message on NFC tag for now

---

References

• [CH23817]
• particle-iot/nrf5_sdk#4

---

Completeness

• User is totes amazing for contributing!
• Contributor has signed CLA (Info here)
• Problem and Solution clearly stated
• Run unit/integration/application tests on device
• Added documentation
• Added to CHANGELOG.md after merging (add links to docs and issues)

---

• [gen 3] NFC support #1606

[avtolstoy]

NRF_TIMER1 cannot be used. It's already in use by Nordic 802.15.4 radio driver: https://github.com/particle-iot/openthread/blob/master/third_party/NordicSemiconductor/drivers/radio/nrf_802154_config.h#L133

[YutingYou]

We've run out of timer resource, I'd like to release the timer in button hal, we have below choice for button debounce timer, or you can add other suggestion:

• Use FreeRTOS timer in Device OS and use Timer 2 in bootloader
• Use a high-precision timer to make a general software timer just like app timer, then we can use it in Bootloader and Device OS
• Add a software timer handler in HAL_SysTick_Handler(), if we start the button timer, we set a timer flag, then we check the flag in HAL_SysTick_Handler()

I'd prefer the third one, since the handler won't take a long time.

Timer resource:

RTC0: Softdevice
RTC1: FreeRTOS
RTC2: OpenThread

Timer0: Softdevice
Timer1: Radio
Timer2: Button_hal
Timer3: Usart
Timer4: Usart

[avtolstoy]

Agreed, I don't think we have any other choice at the moment. Moreover on Gen 3 devices this shouldn't cause any issues for FreeRTOS, since FreeRTOS is run off of RTC timer instead of SysTick.

[avtolstoy]

While we do not have a formal style guide at present, I think lowercase snake_case should be preferred for new HALs. This should apply both to function names and type names.

[YutingYou]

Changed

[avtolstoy]

Can the payload in theory be more than 2^16 bytes (not taking into account our specific microcontroller)? If yes, I suggest we change this to size_t. A reserved void* argument here also sounds like a good idea.

[YutingYou]

Changed

[avtolstoy]

An additional void* ctx argument and a change in NfcEventCallback signature ((NfcEventType type, NfcEvent *event, void* ctx)) sounds like a good idea.

[YutingYou]

Added it

[avtolstoy]

@YutingYou Will the wiring API be a separate PR?

Please also add a new dynalib exporting these new NFC functions, otherwise they will not be accessible in modular firmware from the user part.

[YutingYou]

@avtolstoy wiring API will be a separate PR. Added dynalib support.

[llacom]

I'm trying to build the sample application. I copied the code in user/applications/nfc/application.cpp and build it using make all PLATFORM=argon APP=nfc from the firmware/modules folder.

The error I get:

../../../build/target/user/platform-12-m/applications/nfc//libuser.a(application.o): In function `setup':
/home/dromar/projects/particle-firmware/firmware/user/applications/nfc/application.cpp:35: undefined reference to `app_error_handler'
/home/dromar/projects/particle-firmware/firmware/user/applications/nfc/application.cpp:39: undefined reference to `hal_nfc_type2_init()'
/home/dromar/projects/particle-firmware/firmware/user/applications/nfc/application.cpp:40: undefined reference to `hal_nfc_type2_set_callback(void (*)(nfc_event_type_t, nfc_event_t*, void*))'
/home/dromar/projects/particle-firmware/firmware/user/applications/nfc/application.cpp:41: undefined reference to `hal_nfc_type2_set_payload(void const*, unsigned int)'
/home/dromar/projects/particle-firmware/firmware/user/applications/nfc/application.cpp:42: undefined reference to `hal_nfc_type2_start_emulation()'
collect2: error: ld returned 1 exit status

Those symbols were defined on libhal.a but not in libhal-dynalib.a. Trying to solve it, I added a file hal-dynalib/src/hal_nfc.c with the following:

#include "hal_dynalib_nfc.h"

Now the symbols are in libhal-dynalib.a but the same error persist. I'm probably misunderstanding how dynalib works or the corrent build process.

[avtolstoy]

void* reserved

[avtolstoy]

void* reserved

[avtolstoy]

void* reserved

[avtolstoy]

Any functions taking a callback should have a void* context argument which should be stored along with the callback itself. The stored context should be passed as an argument to the callback function.

[avtolstoy]

Nitpicking: prefer type* to type *

[avtolstoy]

Nitpicking: prefer const char* to const char *.

[avtolstoy]

Nitpicking: prefer const char* to const char *

[avtolstoy]

Consider using:

class NfcTagType2 {
public:
    NfcTagType2& instance() {
        static NfcTagType2 inst;
        return inst;
    }
protected:
    NfcTagType2() {
        ...
    }
}

#define NFC NfcTagType2::instance()

to save on flash space/RAM when the application is not using NFC.

[aroller]

I posted on the community forum the attempt to build this branch on a Xenon before @avtolstoy requested the latest changes. @YutingYou I'm not much help at coding the device-os, but I'm ready to help with building, testing and documenting when changes are applied. Let me know if I can be of assistance. Thanks for your efforts with the NFC API.

[YutingYou]

@llacom Sorry for the late reply, the HAL layer example is only for monolithic firmware, your issue is caused by I didn't export NFC functions as C function. It was fixed in the latest commit. The HAL example also uses some unexported function, so I'd suggest using wiring API to continue your test.

@aroller You should meet the same issue as @llacom met, please try again, if you got any issue or suggestions, feel free to let me know.

[avtolstoy]

🎉

[YutingYou]

Sure thing, it seems there is no example for the new API, I'll look into it.