Skip to content

Porting to New Chipset

If you prepare to port this application to the new Wi-Fi module or other platform (e.g. a linux gateway), you need to re-implement the following functionalities carefully.

By the end of this article, you will have modified to following files

  • platform/<YOU_PLATFORM_NAME>/source/timer.c
  • platform/<YOU_PLATFORM_NAME>/source/systime.c
  • platform/<YOU_PLATFORM_NAME>/source/mutex_protection.c
  • platform/<YOU_PLATFORM_NAME>/source/tcp_common.c
  • platform/<YOU_PLATFORM_NAME>/source/vuart.c
  • platform/<YOU_PLATFORM_NAME>/source/mqtt_wrapper.c
  • platform/<YOU_PLATFORM_NAME>/source/ota_handler.c
  • platform/<YOU_PLATFORM_NAME>/source/device_reset_handler.c
  • platform/<YOU_PLATFORM_NAME>/source/platform_utils.c
  • platform/<YOU_PLATFORM_NAME>/source/provisioning_server.c
  • platform/<YOU_PLATFORM_NAME>/source/semi_client.c

Timer

Timer is a very important feature for system running, so you need to implement correct timer wrapper to fit your platform.

Steps

  1. You can see the declaration of the timer interface in the library/timer/include/timer.h
  2. Follow this header file to implement each interface, and put the implementation code to platform/<YOU_PLATFORM_NAME>/source folder.
  3. Name your implementation file as timer.c.
  4. Reference your development tool setting to link the right implementation.

Systime

Systime is for setting system timer and related system time function.

Steps

  1. You can see the declaration of the system interface in the library/systime/include/systime.h
  2. Follow this header file to implement each interface, and put the implementation code to platform/<YOU_PLATFORM_NAME>/source folder.
  3. Name your implementation file as systime.c.
  4. Reference your development tool setting to link the right implementation.

Mutex

Mutex is for critical section protection in multi-threading environment.

Steps

  1. You can see the declaration of the mutex interface in the library/mutex_protection/include/mutex_protection.h
  2. Follow this header file to implement each interface, and put the implementation code to platform//source folder.
  3. Name your implementation file as mutex_protection.c.
  4. Reference your development tool setting to link the right implementation.

TCP Socket

We use TCP socket to connect to the Exosite’s file server to download the latest firmware, so we introduce the TCP common interface to make the OTA process easier.

Steps

  1. You can see the declaration of the TCP common interface in the library/tcp_common/include/tcp_common.h
  2. Follow this header file to use your platform’s TCP socket functionalities to implement each interface, and put the implementation code to platform/<YOU_PLATFORM_NAME>/source folder.
  3. Name your implementation file as tcp_common.c
  4. Reference your development tool setting to link the right implementation.

MQTT

MQTT is the main communication protocol to connect to the Exosite cloud, so you need to port your platform’s MQTT functionalities to the MQTT wrapper.

Steps

  1. You can see the declaration of the MQTT interface in the library/mqtt_wrapper/include/mqtt_wrapper.h
  2. Follow this header file to use your platform’s MQTT functionalities to implement each interface, and put the implementation code to platform/<YOU_PLATFORM_NAME>/source folder.
  3. Name your implementation file as mqtt_wrapper.c
  4. Reference your development tool setting to link the right implementation.

UART

UART is the only interface to connect to smart home appliance, so you need to use you platform’s uart features to implement the application’s virtual uart functionalities.

Steps

  1. You can see the declaration of the virtual uart interface in the library/vuart/include/vuart.h
  2. Follow this header to implement each vuart function, and put the implementation code to the platform/<YOU_PLATFORM_NAME>/source folder.
  3. Name your implementation as vuart.c
  4. Reference your development tool setting to link the right implementation.

OTA

OTA stands for over-the-air firmware update. It’s a necessary feature for today’s IoT application, so we provide a common interface for OTA function. You can follow this interface to do the implementation depending on your platform.

Steps

  1. You can see the declaration of the OTA function interface in the include/ota_handler.h.
  2. You can see the example of the implementation code in platform/wiced/source/ota_handler.c. You don’t need to modify the whole file. Therefore, you should just re-implement the ota_handler_start() function, the ota_handler_deinit() function, and the write_ota_data_to_dct() function (write the firmware data to the flash) to adapt to your platform. By the way, you can also reference the test code in test/ota_test.c to write an ota functional test to verify your code correctly.
  3. Put the implementation code to the platform/<YOU_PLATFORM_NAME>/source
  4. Name your implementation as ota_handler.c
  5. Reference your development tool setting to link the right implementation.

WIFI Provisioning

WIFI provisioning (AP mode) is a basic functionality for a WIFI communication module. We define a simple mechanism, which is a simple https server, to set SSID and password to the WIFI module. Because there are still some platform dependent issues here, you need to implement this server by your platform web server function. Therefore, you can reference the original implementation code (provisioning_server.c).

Steps

  1. You can see the declaration of the WIFI provisioning function interface from include/provisioning_server.h.
  2. Follow this header to implement WIFI provisioning server functionalities, and you can use the platform/wiced/source/provisioning_server.c as a reference.
  3. Put the implementation code to the platform/<YOU_PLATFORM_NAME>/source
  4. Name your implementation as provision_server.c
  5. Reference your development tool setting to link the right implementation.

Note

  • The value in the provision parameters from mobile app will use URL encoding method, so you need to decode the encoding value. For example, ssid=abc&cd1 will be encoded to ssid=abc%26cd1, so you need to decode it to "abc&cd1".
  • The serial number is generated from the upper logical layer, and this parameter will pass to the provisioning_server_init function. Therefore, you shouldn't change the serial number by yourself. The serial number rules are as below:([0-9A-Fa-f]{24})
    1. Only accept the hexadecimal string format
    2. Accept the upper case and lower case character and numbers
    3. Only accept the 24 bytes string length

Device Reset Handler

Device reset handler defines how you want to software reset your platform when the device receives the reset command from the cloud. We've already defined the basic logic (as described in reset-thread_main() function) in the platform/wiced/source/device_reset_handler.c. Follow the steps below to set this up.

Steps

  1. You can see the declaration of the device reset handler interface from include/device_reset_handler.h.
  2. To enable device reset handler, use the thread function offered by your platform to register the reset_thread_main() function in the device_reset_handler_start() function implementation.
  3. Put the implementation code to the platform/<YOU_PLATFORM_NAME>/source
  4. Name your implementation as device_reset_handler.c
  5. Reference your development tool setting to link the right implementation.

Note

For custom reset function, use device_reset_handler.c as placeholder for rewriting your reset function.

Platform_utils

Platform_utils includes all the platform dependent utilities, which are file read/write utilities, WIFI utilities, mdns function, and system reboot function.

Steps

  1. You can see the declaration of the platform_utils interface from include/platform_utils.h
  2. Follow this header to implement platform utilities, and you can use the platform/wiced/source/platform_utils.c as reference.
  3. Put the implementation code to the platform/<YOU_PLATFORM_NAME>/source
  4. Name your implementation as platform_utils.c
  5. Reference your development tool setting to link the right implementation.

Note

If you want to support multiple NTP servers(more than the default one), you can implement it in the platform_utils_sync_time_from_ntp() function.

Assert

Assert function is for asserting the unexpected behavior.

Steps

  1. You can see the declaration of the assertion function in library/assertion/include/assertion.h
  2. We support Linux and ARM platform in the current implementation, so you need to implement your platform function if it’s not Linux nor ARM platform.

Entry Point

Application entry point (main function)

Steps

  1. You should create your own application entry point file depending on your platform mechanism.
  2. Initialize your platform function in this file.
  3. Put the app_logic_init function and create a thread for app_logic_thread_main function in this file.
  4. You can reference platform/wiced/source/semi_client.c or platform/linux/source/semi_client.c to understand what you should do in the file.
  5. Put the implementation to the platform/<YOU_PLATFORM_NAME>/source
  6. Reference your development tool setting to link the right implementation.

Note

Please use utility_do_wifi_error_action() function to handle Wi-Fi connection error events.

Porting Checklist

Here is a list of all the files you should have modified for the porting:

  • platform/<YOU_PLATFORM_NAME>/source/timer.c
  • platform/<YOU_PLATFORM_NAME>/source/systime.c
  • platform/<YOU_PLATFORM_NAME>/source/mutex_protection.c
  • platform/<YOU_PLATFORM_NAME>/source/tcp_common.c
  • platform/<YOU_PLATFORM_NAME>/source/vuart.c
  • platform/<YOU_PLATFORM_NAME>/source/mqtt_wrapper.c
  • platform/<YOU_PLATFORM_NAME>/source/ota_handler.c
  • platform/<YOU_PLATFORM_NAME>/source/device_reset_handler.c
  • platform/<YOU_PLATFORM_NAME>/source/platform_utils.c
  • platform/<YOU_PLATFORM_NAME>/source/provisioning_server.c
  • platform/<YOU_PLATFORM_NAME>/source/semi_client.c

After your modification is complete, you can send a ZIP file with all your code to Exosite's support for review.