XDK110: Guide Workbench First Steps Document revision 2.0 Document release date 17.08.17 Workbench version 3.0.0 Document number BCDS-XDK110-WB-FIRST-STEPS-GUIDE Technical reference code(s) Notes Data in this document is subject to change without notice. Product photos and pictures are for illustration purposes only and may differ from the real product’s appearance. Subject to change without notice Workbench First Steps Guide Cross-Domain Development Kit XDK110 Platform for Application Development Bosch Connected Devices and Solutions
Transcript
XDK110: Guide Workbench First Steps
Document revision 2.0 Document release date 17.08.17 Workbench version 3.0.0 Document number BCDS-XDK110-WB-FIRST-STEPS-GUIDE Technical reference code(s) Notes Data in this document is subject to change without notice. Product photos and pictures are for illustration purposes only and may differ from the real product’s appearance. Subject to change without notice
Workbench First Steps Guide
Cross-Domain Development Kit XDK110 Platform for Application Development
The Workbench First Steps Guide provides the first steps in the usage of the XDK Workbench and the XDK. This includes a major overview of the features of the XDK Workbench and how to get started with an own application on the XDK. Additionally, some useful coding features of the XDK Workbench are described.
Table of Contents
This guide postulates a basic understanding of the XDK Workbench. For new users we recommend going through the Workbench Installation guide at xdk.io/guides first.
2. HELLO WORLD CODE EXAMPLE 15 .........................................................................................2.1 HELLO WORLD OPERATING TASK 15 .........................................................................................2.2 HELLO WORLD TIMER TASK 17 .................................................................................................
4. USEFUL FEATURES OF THE XDK WORKBENCH 21 ...............................................................4.1 SHOWING LINE NUMBERS 21 ....................................................................................................4.2 ENABLING AUTOSAVE BEFORE BUILDING A PROJECT 21 ..............................................................4.3 ADDING A NEW INTERFACE 21 ...................................................................................................4.4 RENAME A PROJECT IN THE XDK WORKBENCH 23 ....................................................................
5. DOCUMENT HISTORY AND MODIFICATION 25........................................................................
1.1 Opening the XDK Workbench Start the XDK Workbench by clicking on the XDK icon on your desktop. The default path of the application is located in C:\XDK-Workbench\XDK-Workbench.exe. During the startup a splash screen appears. The welcome screen will be shown afterwards.
Picture 1: Welcome Screen of the XDK Workbench
!
The welcome screen is sectioned in three parts: Hands-On & Documentation (upper left), Feedback (upper right) and the XDK-Examples (lower left).
1.1.1 Hands On & Documentation
This section contains four buttons.
• Click&Go: Access the workspace set up for a quick start • Getting Started: The shortcut to the XDK Forum for community interaction • XDK Docs: This button will open the documentation • Eclipse Docs: This button will open the Eclipse help (XDK Workbench ist based on Eclipse)
1.1.2 Feedback
Clicking the respective button will take you to the matching XDK community forum section to get help, to post a new application or to post an improvement. Inside the community you will find hints, tips and tricks and you can get in touch with other developers.
1.1.3 XDK Examples - Basics
The XDK comes with a variety of application examples. Choose one example and click on it. The chosen example will be imported into the workspace. The following examples are currently included:
XdkApplicationTemplateThis is an empty template serving as a starting point for new projects.
LedsAndButtonsThis example contains a showcase for the use of LEDs and buttons.
SdCardExampleThis example contains the showcases for the use of the SD card file system.
1.1.4 XDK Examples – Networking
HttpExampleClientThis example shows how to use the network stack to perform an HTTP Client Request. HTTPS is not yet implemented. If an encryption is required, it is recommended to implement an own small encryption. (e.g. Base64)
WlanNetworkManagementThis example demonstrates how to use the XDK WLAN Abstraction to scan for networks, join networks, set a static IP address or dynamically obtain an IP address via DHCP.
Lwm2mExampleClientThis example demonstrates how to register with a LW-M2M Server including the standard LW-M2M Objects. Unencrypted and encrypted communication is both supported.
SendDataOverUdpThis example demonstrates how to send arbitrary data over WLAN as a UDP Broadcast.
1.1.5 XDK Examples - Sensors
SendAccelerometerDataOverBleThis example streams raw accelerometer data from the BMA280 Acceleration sensor via Bluetooth Low Energy (BLE). The Alpwise Data Exchange Profile is used; Alpwise iOS/Android App is required. Send "start" to XDK, so that streaming of data begins.
SendVirtualSensorDataOverUsbThe example will print out raw data from all available physical sensors. The example captures the sensor data of all sensors in one cycle.
StreamSensorDataOverUsbThis example will print out data from the virtual sensors over the USB port. The particular sensor can be selected in the source code.
SendAccelDataOverUdpandBleIf you want to use WLAN and BLE, here is a demo for this. This example demonstrates how to read sensor values from the BMA280 Acceleration sensor and send the data over WLAN (UDP Broadcast) and Bluetooth Low Energy via the Alpwise Data Exchange Profile. Either use your Android or iOS mobile phone (see Android or iOS App Store) to connect to XDK and receive the data. Send "start" to XDK via Bluetooth Low Energy, so that streaming of data begins.
SensorLwm2mClientThis example demonstrates how to register with a LWM2M Server, including the standard LWM2M and IPSO Alliance sensor objects with very little necessary editing. The implementation supports both insecure and secure connections, which can be chosen accordingly.
VirtualXdkDemoThis example demonstrates the XDK's sensors, using an Android/iOS app, to which the XDK sends its data using BLE. The app visualizes the data in real time, allowing for a great presentation of the XDK's features.
1.2 XDK Workbench – Workspace (XDK View) Let’s get started with the workspace view.
Picture 2: XDK workspace window
! The default Workbench setup is split into four main tiles per default: XDK Devices (upper left), Project Explorer (lower left), Editor (upper right) and Console (lower right). The menu bar is located at the top of the window as usual. Each tile can be maximized or minimized by clicking on the respective symbol on the tile. Resizing is possible by changing the position of the tile borders. You can change the perspective by clicking on the “Open perspective” button (see 1.1.1).
1.2.1 The menu bar
Picture 3: The menu bar
!
The menu bar contains all necessary functions of the XDK workbench. There is a classic menu structure and a symbols bar. Some entries are available only in a suitable context (e.g. Refractor). The symbols are only active highlighted if a matching context exists.
1. Project/Other same as File\New, opens the Project Wizard (see picture 11) 2. Save/Save all saves (all) files shown in the editor. 3. Build all compiles all files. 4. Opens C Project Wizard; shows all examples per default. 5. Opens the welcome page. 6. External Tools: click on the black arrow for more options. Same structure as in the “Run” menu above. 7. Open Element opens the element menu. 8. Search opens the File/C++ search menu, can also be reached via “Search” above. 9. Toggle Mark Occurrences: marks occurrences in the editor. 10. Next/Previous Annotation; jumps to the next/previous annotation. Choose the annotation type by clicking on the black arrow. 11. Last Edit Location sets the cursor to the last edited position in the editor. 12. Forward…/Back to… switches between the register cards in the editor.
Picture 5: Quick access bar
!
1. Quick Access; shows the possibilities of the Workbench by simply typing in characters or numbers sorted by categories. 2. Open perspective; changes the Workbench view according to the chosen perspective. 3. After choosing a different perspective the matching symbol appears right from the “Open perspective” button for faster access. The buttons disappear with right-click/close.
The XDK devices list (picture 6) shows a list of previous and currently connected XDKs. The three buttons on the right allow to flash, boot or to debug the device. For activating the debug mode the JLink adapter (sold separately here) must be connected. Right clicking on the XDK will open the context menu. You can choose “Go to Bootloader” and “Flash Bootloader”. Also you can rename the XDK device here. (Picture 7).
Picture 7: Connected XDK devices
!
The COM and JLink buttons in the device list (picture 7) can also be manually activated or deactivated. The COM button enables the current connection between the XDK and the PC. The JLink button enables the current connection over the JLink of the XDK to the PC. What a JLink does will be described in section 1.2.2.3.
1.2.2.1 Flash Button
Select a project from the Project Explorer or import an example from the XDK welcome screen. Press the Flash button. The XDK Workbench then compiles the project.The XDK is then put into bootloader mode. The compiled project is now transferred to the XDK, which boots automatically on completion.
Picture 8: XDK flash view
!
1.2.2.2 Boot/Reboot The button is context-sensitive and can change between Boot and Reboot, depending on the current mode of the XDK. By pressing the Boot button the XDK boots from bootloader to application mode. By pressing the Reboot button XDK switches from application mode to bootloader mode.
1.2.2.3 Debug For debugging a JLink adapter is required. Choose a previously compiled project. The XDK Workbench configures the debug configuration automatically. The binary is downloaded to the XDK and the debugger starts. The XDK Workbench proposes to switch to debug perspective.
To get some system relevant information like the connected XDK’s CoreID or the USB serial number you can mouse over a device . A window will appear and display the information. The CoreID is unique for each XDK and is based on it’s micro controller ID.
Picture 9: XDK device information
!
1.2.3 Project Explorer
The project explorer stores all current XDK projects. It allows the creation of new projects and the implementation of example projects from the welcome screen. It is also possible to import and export projects from and to the XDK community.
Picture 10: Project explorer
!
Creating a new Project
It is possible to create new projects in the project explorer. For this you have to right-click in the project explorer area -> select New -> select Project.
Picture 11: Project wizard
!
Now you have to choose between certain project types. It is recommended to create a C project.
Open XDK Project Template and then select Application Template. This will include the required BCDS XDK Toolchain. The toolchain is required to compile and flash an application onto the XDK.
The editor area of the XDK workbench allows entering and editing of code lines. More functions are available by using the context menu.
1.2.4.1 Code Editor - Autocompletion
Code autocompletion is an useful feature of the XDK workbench. Type the starting character and complete the name with ctrl + space. With this shortcut it can be avoided to type long variable names. Additionally it is a convenient way to find variables and functions you want to use from the included libraries.
The Console tab shows an overview of the status of the Workbench, allows sending data to the XDK and shows output coming from the XDK via USB. Buttons are available on the upper right side of the tile, depending on the current status. These buttons contain functions like “go to next error”, “clear console”, etc. There are two additional tabs. “Progress” shows the current status of e.g. flashing.
Picture 17: Progress bar
!
You can cancel the operation by clicking on the red button on the right side of the progress bar. The “Problems” tab displays existing problems detected by the XDK Workbench.
This chapter describes the different operation modes of the XDK, how to determine in which mode the XDK is and how to switch between them. Please note that in normal operation, the XDK Workbench will automatically detect the mode it currently is in. Furthermore, the XDK Workbench will try to automatically perform the mode switch that is required for its correct function. However, there may be certain situations in which the automatic detection or the automated switching does not work. In general, the XDK knows the following modes
The XDK bootloader is stored in the first 64 kB of XDKs flash memory. When the bootloader is no longer present or becomes corrupted, an update or recovery is only possible via the JLink JTAG Adapter. The bootloader allows uploading XDK applications via USB (see XDK Bootloader in the XDK General for further information). The bootloader is write-protected and can only be overwritten or updated using the JLink JTAG Adapter (sold separately) via XDK Workbench. When powering up, the XDK will automatically go into the bootloader mode, which is indicated by the red LED. If the XDK finds a valid application, the bootloader will automatically turn off the red LED and start the application. If no valid application is found or the XDK is forced to go into bootloader mode, the yellow LED indicates if the XDK is successfully connected to a PC. Once the red and yellow LEDs are solid on, the XDK shows up in the device view of the XDK Workbench and can be programmed.
How to engage the Bootloader
The XDK can be set into bootloader with a useful feature of the XDK workbench. Right-click on the XDK and select Go to Bootloader. In the case that the XDK does not respond (and is possibly not even recognized over USB), you can manually force the XDK into boatloader mode via Approach 1
Approach 1
• Switch off XDK • Press and hold Button 1 • Turn on XDK • Release Button 1 as soon as red LED turns on
This approach is the "last resort" when XDK does not respond. Even if the XDK is not recognized over USB, approach 1 will work. There are two more possibilities to set XDK into bootloader mode:
Approach 2
• Get XDK into application mode (typically by turning it on) • Connect it to your PC • Start XDK Workbench • Right-click on your XDK in the XDK Device View and select Go to Bootloader
The second approach will set a flag in the user page of the MCU of XDK. When XDK reboots, the bootloader reads the flag and engages itself. Only after booting an application, the flag is reseted.
Approach 3
• Get XDK into application mode (typically by turning it on) • Connect it to your PC • Connect to XDK with a serial terminal program (see XDK_USB_DEVICE_HANDLING_Terminal) • Send the following string: #reBoot$ • XDK will automatically reboot and go into the bootloader
This is technically the same as Approach 2, but it is to mention that it is possible to send commands to the XDK via the serial interface. More information on the commands that can be sent by USB can be found in the User Guide in chapter 3.5.1.3.21. Binary images uploaded via the bootloader must be transferred in the XMODEM-CRC format.
1.2.6.2 Application Mode/Startup Guide
This simple guide is intended for developers who are going to develop applications for XDK, to know the basic startup procedure of the system before they start writing their application. The XDK software can be configured to start in two ways as described below. The configuration can be done using the BCDS_SYSTEM_STARTUP_METHOD macro present in the application makefile. By default the XDK is shipped with DEFAULT_STARTUP enabled. Refer the code block below representing the change.
export BCDS_SYSTEM_STARTUP_METHOD=CUSTOM_STARTUP
Default Startup
The main() function implemented in the SystemStartUp module will be the first C function executed during power ON and it does the following: 1. EFM32 chip is configured to a proper state with the help of the library function exported by emlib. 2. All interrupt sources are configured to maximum priority to ensure that ISR runs at highest priority. 3. System peripherals like GPIO, I2C and USB are initialized to a proper state. 4. GPIO pins are configured to their default value. 5. The user page module is initialized. It is used to save configuration information like Wi-Fi MAC address, Bluetooth MAC address, etc., in the user page area of flash. 6. Creates a default application specific initialization CmdProcessor and start it. 7. Gives control to the operating system by starting the task scheduler of FreeRTOS.
Custom Startup
The custom startup procedure will exclude steps 3 to 5 of the default startup procedure described above to give users the flexibility in initializing system peripherals. Users can choose to initialize and configure the peripherals which they want to use in their application. If the custom startup procedure is configured, users have to ensure that the GPIO pins they are using are initialized to a proper default state. In both of the above configurations XDK's SystemStartUp module will schedule a default application-specific initialization function appInitSystem which will run in the CmdProcessor context with task priority 2.
Note: main.c is required to start up the freeRTOS operating system. All code implementations will take place in additional interface header .h files and implementation .c files. Please refer to the section 5.3 how to add new interfaces to the XDK.
1.3 Application Template The XDK Workbench provides a recommended project-template for own projects. This template is called XdkApplicationTemplate. It includes the BCDS XDK toolchain that is required to compile and flash a project to the XDK.
Picture 19: XDK application template
!
The XdkApplicationTemplate can be imported in two different ways. One is to import the template over the welcome screen by clicking on the example XdkApplicationTemplate. The other one is to generate the XdkApplicationTemplate as project as described in the section 1.2.3.
2.1 Hello World Operating Task This section gives a small introduction about the operating and timer tasks. It should give the user a basic understanding on how these tasks work via a hello world implementation. First, operating tasks will be presented.
Note: main.c is required to start up the freeRTOS operating system. All code implementations will take place in additional interface header .h files and implementation .c files. Please refer to the section 5.3 how to add new interfaces to the XDK.
Code 4: Hello world implementation - main.c
!
/* system header files */ #include <stdio.h> #include "BCDS_Basics.h"
/* global variables ***************************************************** */ static CmdProcessor_T MainCmdProcessor;
/* functions */
int main(void){ /* Mapping Default Error Handling function */ Retcode_T returnValue = Retcode_initialize(DefaultErrorHandlingFunc); if (RETCODE_OK == returnValue){ returnValue = systemStartup(); } if (RETCODE_OK == returnValue){ returnValue = CmdProcessor_initialize(&MainCmdProcessor, (char *) "MainCmdProcessor", TASK_PRIO_MAIN_CMD_PROCESSOR, TASK_STACK_SIZE_MAIN_CMD_PROCESSOR, TASK_Q_LEN_MAIN_CMD_PROCESSOR); } if (RETCODE_OK == returnValue){ /* Here we enqueue the application initialization into the command * processor, such that the initialization function will be invoked * once the RTOS scheduler is started below.*/ returnValue = CmdProcessor_enqueue(&MainCmdProcessor, appInitSystem, &MainCmdProcessor, UINT32_C(0)); } if (RETCODE_OK != returnValue){ printf("System Startup failed"); assert(false); } /* start scheduler */ vTaskStartScheduler(); }
2.2 Hello World Timer Task An other type of tasks beside the operating tasks are the timer tasks. These have the advantage to run an application periodically without manual implementations of any infinite loops. How to use them will be shown in the implementation code 3 of the hello world application with timer tasks:
Code 6: Hello World Timer Task Application File - application.c
!
/* system header files */ #include <stdio.h> #include <BCDS_Basics.h>
/* create timer task to print Hello World in the output console every three seconds */ /* Validated for portMAX_DELAY to assist the task to wait Infinitely (without timing out) and ticks cannot be 0 in FreeRTOS timer. So ticks is assigned to 1 */ applicationTimer = xTimerCreate( (char * const) "Test Application to print Hello World", SECONDS(3), TIMER_AUTORELOAD_ON, NULL, printHelloWorld);
/*start the timer*/ xTimerStart(applicationTimer, TIMERBLOCKTIME); }
/* This is a template function where the user can write his/her custom application */
3. Sensor Example Following the first own sensor measuring will be implemented. The reason why the light sensor will be implemented is because the search for mistakes is relatively simple. As described before the example will be implemented in the recommended XdkApplicationTemplate project.
Note: appInitSystem() is required for the example and should not be deleted
To provide all necessary functions of the light sensor, the interface BCDS_LightSensor.h has to be included, like it is shown in the following code 7. This interface contains all required functions to initialize and use the light sensor.
Code 7: Including sensor specified header
!
Alternatively an interface can be included that holds references to all sensors of the XDK which makes them accessible. Please not that this interface only needs to be included once, no matter how many sensors are used. This is in contrast to the sensor specific interface where one is needed for each sensor in use.
Code 8: Including primary header
!
Note: The interface XdkSensorHandle.h has the advantage that it includes the header file BCDS_LightSensor.h of the light sensor too and it also contains the interfaces of all other sensors of the XDK.
3.1 Initializing light sensor The next step is to initialize the light sensor.
Code 9: Implementation of the initialization of the light sensor
!
/* Include this code in XdkApplicationTemplate.c */ #include "BCDS_LightSensor.h"
#include "XdkSensorHandle.h"
/* Include this code in XdkApplicationTemplate.c */
The first expression is used to generate a return code. Afterwards the light sensor is initialised by LightSensor_init(), which returns the return code that can be checked if the sensor was correctly initiated.
3.2 Reading light sensor After the correct initialization the sensor is ready to read. The following code snippet describes how a function reading the incoming sensor data has to be implemented.
Code 10: Implementation to read the light sensor data
!
In code 7 the sensor value of the light sensor is read. The first expression is related to the freeRTOS operating system and so not necessarily needed. It is only there to prevent a warning of the compiler. The following declaration of the variable milliLuxData describes the generation of a 32-bit variable where the light sensor data is stored. It follows the declaration of the condition state returnValue if the data could be read. The next line of code describes the actual reading of the light sensor data via LightSensor_readLuxData(). The display of the data takes place in the if bracket, the printf() is only executed if the return value of LightSensor_readLuxData() is RETCODE_OK. This means that the reading of the light sensor data was successful.
The initialization of the light sensor and a function that reads its data are implemented. Now a timer or operating task has to be implemented that periodically reads the data und prints it to the XDK Workbench console. Additionally to the code lines above the implementation of the timer task takes place in appInitSystem(): The following code lines shows how to implement the required timer task.
/* Include this code in XdkApplicationTemplate.c */
The first three variable declarations are required properties for the timer task. This includes the periodicity of the timer, an one second delay and the maximal block time. For more information please refer to the freeRTOS guide that you can find here.
Additionally to the declaration of a timer handle for the timer task is required. This handle LightSensorHandle gives direct access to the timer task and can be used for example to start or stop the task. The next line of code executes the initialization of the light sensor. Finally the last two lines of code create and start the required timer task. The first one xTimerCreate() creates the timer task and the second one xTimerStart() starts the timer task.
Finally the first own sensor application is ready be built and flashed to the XDK.
/* Include this beneath BCDS_UNUSED(param2); in appInitSystem() */
4.1 Showing Line Numbers This section describes how to set useful configurations in the XDK Workbench. First, you should enable autosaving before building. The following screenshot shows where the configuration can be found in Window > Preferences and which checkbox has to be selected.
Picture 20: Line Numbers
!
4.2 Enabling autosave before building a project Another useful setting is autosaving before flashing. This feature is especially helpful if there are small changes in the code done and not saved before the project was flashed to the XDK. Sometimes it can happen that code that was not saved is flashed to the XDK and it runs for example a non-functional application on the XDK besides working code. The following screenshot describes where autosaving can be enabled found in Window > Preferences.
Picture 21: Enabling autosave
!
4.3 Adding a new Interface This section describes how to add new interfaces to an existing application in the XdkApplicationTemplate or in other projects.
There are two ways to add new source and header files to an existing project. Import existing files into the project or create a new one. Existing files can be placed in the project folder and simply imported in the XDK
Workbench by refreshing the project. The following Screenshot shows how to create both an implementation file and a header file.
Picture 22: Creating a new Interface
!
Note: Both files need to have the correct ending tag, for example the implementation file .c
Picture 23: Creating h.- and c. file
! !
The header file only has to be included in the .c implementation file. Therefore the implementation file has to be additionally added to the makefile of the project. The following screenshot shows where in the makefile the include has to be done. Both works similar for new files or for imported files.
4.4 Rename a Project in the XDK Workbench If you rename a project in XDK Workbench, the project configuration as well as the makefile has to be modified.
1. Click your project in XDK Workbench and select Properties.
2. Go into the C/C++ Build tab and update the BuildDirectory. To do this, click on Workspace and select the "make" folder inside your renamed application.
3. Open up the makefile in your renamed application. You may want to modify the BCDS_APP_NAME, as it defines the name of your executable file afterwards. Furthermore, you may want to add and/or change the files listed in BCDS_XDK_APP_SOURCE_FILES.
Picture 27: Makefile
!
4. And last but not least rename the project name.
