mikroSDK 2.0 Porting Guide¶
The purpose of this document is to demonstrate and provide guidance on how to port parts of mikroSDK to be used with other SDKs and toolchains. This will be very useful in case you wish to use Click board examples in your SDK, or simply wish to use mikroSDK drivers in your project in general.
In order to make it easier to understand, we will go over a practical example,
which shows how to port the GPIO driver from mikroSDK to Microsoft Azure Sphere
The main idea is to add the mikroSDK GPIO driver to the Azure Sphere project and then implement the Azure Sphere SDK high level GPIO driver into mikroSDK HAL (hardware abstraction layer). This way the GPIO high level driver of the Azure Sphere SDK takes care of hardware abstraction.
Once a mikroSDK driver, for example GPIO, is properly ported and a new modified
HAL is created, it enables you to use hundreds of other Click boards that
use GPIO to communicate.
Same applies to the SPI driver, I2C, UART, etc...
A proper porting of a mikroSDK driver results in creation of a new HAL, none or very minimal changes to the Click board driver and minimal changes to the Click board example.
This guide, when broken down, reveals the following steps:
Hardware used in this guide¶
Software used in this guide¶
- Visual Studio Code
- Microsoft Azure Sphere SDK
- GPIO_HighLevelAPP Sample
- mikroSDK 2.0 source code
- Driver source code of both Click boards
You do not necessarily have to have these Click boards. They were used only as an example in this guide. It is possible to use any Click board based on the GPIO module in order to follow this guide.
Setting up PC and installing necessary software¶
First thing you need to do before you start porting mikroSDK 2.0 is to install
the software required for this project. Follow the steps from the guide on
this link to
find out how to configure your PC and your project, including Visual Studio Code
setup, CLI setup, SDK setup, board configuration using CLI and programming
Make sure you choose the correct SDK which contains setup for Visual Studio Code (required for this guide), as there is another version which contains setup for Visual Studio IDE.
After following these steps succesfully, you will be ready to start the mikroSDK porting procedure.
Comparing and understanding the differences between mikroSDK and Azure Sphere SDK¶
The first thing that you should do when trying to port any of the mikroSDK
drivers to your project is to compare your application/project/drivers with the
mikroSDK drivers, the differences and similarities in organization, structure,
It could be useful if you successfully modify your project to run the target Click board on your system. This will allow you to see how the Click board exactly works and what modifications need to be made in order for it to run on your system.
In this example we use Azure Sphere Starter Kit along with the Relay and Signal
Relay Click boards.
Let us examine how to run both of these Click boards on the Azure Sphere Starter Kit by modifying the GPIO_HighLevelApp project. Signal Relay Click will be used on mikroBUS1, while Relay Click will be used on mikroBUS2 slot.
In that project, we will define and initialize GPIO pins which are routed to the two mikroBUS slots:
So, if you wish to control both Click boards at the same time you need to have
the exact number of static global variables (pin objects) determined by the
number of used GPIO pins. These global variables will store the ID of the
initialized pin and will be used to address the desired pin. This is how the
Azure Sphere SDK GPIO driver functions.
In this example we wrote the following code to control the state of the each of the used pins:
Take a look at the following code:
This is how we actually control the state of the relay output.
Now, if we compare this modified example with the default GPIO example (from the GPIO_HighLevelApp), we can notice that the two are very similar and that we didn't have to make a lot of modifications, but they are essential to this code.
Now we can start porting the mikroSDK GPIO driver to the GPIO_HighLevelApp project/Microsoft Azure Sphere SDK.
mikroSDK porting procedure¶
To begin, let us copy all necessary source and header files from the mikroSDK GPIO driver into the project based on the GPIO_HighLevelApp example.
Hardware Abstraction Layer (HAL):
HAL Low Level Layer (HAL LL):
Files in italics are only necessary if you want to implement your SDK into HAL Low Level Layer of the mikroSDK. In this guide, we will put our implementation directly in the HAL layer, so we do not need these files.
We also need the library source code of the Relay Click. It can be downloaded from Libstock, just like other Click libraries.
Relay Click library consists of two files:
In the next step we should take a look at the mikroSDK GPIO driver, HAL (Hardware Abstraction Layer) and HAL Low Level code. If we check the implementation of these layers and compare them with implementation of the GPIO_HighLevelApp example, which includes the GPIO module from the Microsoft Azure Sphere SDK/../../../../applibs/gpio.h, we can conclude that function implementation and pin object structure are similar, but have some differences. Now we have to find a way to include the functions from the applibs/gpio.h library into the mikroSDK GPIO driver layer without making any modifications to this layer. This is imperative in case we want to maintain compatibility with other architectures.
Let us start from the pin object structure. By comparing implementation of the
GPIO_HighLevelApp example with the mikroSDK GPIO driver and HAL layer, we can
see that we can use fields from the pin object structure
mask field, to store the result of executing the
We can make use of the
hal_gpio_direction_t direction parameter to determine
whether to call the
GPIO_OpenAsOutput(), depending on
whether the pin is to be configured as input or output respectively. We will use
hal_pin_name_t name parameter for identifying the selected pin.
Adhering to these guidelines, we can alter the
function, like so:
This parameter will determine which pin that we want to use, and must be
configured by using
relay_cfg_t configuration object. If we want to use two
same Relay Click boards, one in each mikroBUS socket, just like we are doing in
this example, we need to have two
relay_t context objects, one for each Relay
Click board, as well as two
relay_cfg_t configuration objects.
Now that we have adjusted the pin object structure from mikroSDK, it’s very easy to modify all other functions that are used in the GPIO module of the mikroSDK project. All that is left to change now is for GPIO HAL to call functions from the GPIO library of the Microsoft Azure Sphere SDK (applibs/gpio.h). The pin object structure, as the main argument of all of these functions will provide everything they require.
The similar code which allows to control the selected GPIO can be found in the mikroSDK project in the GPIO HAL Low Layer (hal_ll_gpio.c), it can be used in our implementation with necessary modifications. Also, in this case it’s completely correct if we put the low level implementation directly in the GPIO HAL (hal_gpio.c).
Here is how we modified the functions from the mikroSDK GPIO HAL layer:
By doing this, we have completed the mikroSDK porting procedure for the GPIO
module. Now, there is a new low level implementation of the GPIO HAL which uses
functions from the Microsoft Azure Sphere SDK GPIO layer.
mikroSDK GPIO driver, together with all other drivers, has a unique interface which allows controlling of the GPIO module by calling the functions from the GPIO HAL. This results in having unique functions to control the GPIO module for any supported architecture. The same applies to other mikroSDK modules.
Now, if we take a look at the Relay Click or Signal Relay Click driver, we can see that both of them use functions from the mikroSDK GPIO driver layer in their implementation. That means that we are now able to include this exact Click driver in our code to perform the control of the Relay/Signal Relay Click on the Azure Sphere Starter Kit, or any other supported board -- a same Click driver with unique interface for all supported boards and architectures.
If we go back to the GPIO_HighLevelApp project, which we modified to be able to control the Relay and Signal Relay Click boards, now there is a new, much better solution. Because of the changes we've made, mikroSDK project is now a part of the Microsoft Azure Sphere SDK project and that allows us to use the Relay driver directly in our GPIO_HighLevelApp project. This also means that, if we wish to use any other Click driver based on the GPIO module, we just need to download it from Libstock and include it in our project.
The final step would be to alter our example, so that it calls functions from
the Relay driver, just like in the official mikroSDK project.
In the example below, we placed two Relay Click boards in each mikroBUS socket, both controlled by the same Relay driver:
Programming and testing¶
In case you haven't followed all the steps from this guide about what is necessary to do if you want to program your device and test your project, now would be the time to do so and to make sure you succesfully completed the following steps:
- creating a Microsoft account (if you do not have one already)
- claiming your device
- configuring networking for development
- building a high-level application
This will allow you to start debugging in the Visual Studio Code
[ F5 ], or to run your project without debugging
[ Ctrl+F5 ].
If everything was successful, meaning there were no errors in the output
terminal, you should see how your device/board performs the controlling of these
two Relay Click boards.
This is an enough to verify that the mikroSDK porting procedure was successful.
You can repeat the same procedure to port any other driver from the mikroSDK project by using some other Click board, which utilizes that module (ADC, I2C, SPI, et cetera).
On the links below you can see different ways of porting Click board examples: