CodeBlocks IDE User Guide

JN-UG-3028 Revision 1.8 4-Dec-2008

Jennic

CodeBlocks IDE User Guide

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic
4
4 5 5 5 5

Contents
About this Manual
Organisation Conventions Acronyms and Abbreviations Related Documents Feedback Address

1 Overview 2 QuickStart to Using Code::Blocks

2.1 Example Applications 2.2 Opening and Building an Example Project

7 9
9 10

3 Creating and Building Your Own Projects

3.1 Code::Blocks Projects 3.2 Creating a Project 3.3 Working On Your Project 3.4 Building Your Project 3.4.1 Specifying Paths 3.4.2 Performing a Build 3.4.3 Dealing with Compilation Errors

11
11 12 17 18 18 20 21

4 Downloading an Application Binary

4.1 Pre-requisites 4.2 Download Procedures 4.2.1 Using the Integrated Flash Programmer 4.2.2 Using a Separate Flash Programmer

23
23 23 24 26

5 Debugging Application Code

5.1 Using the Integrated Debugger 5.1.1 Configuring the Integrated Debugger 5.1.2 Operating the Integrated Debugger 5.1.3 Tips on Using the Integrated Debugger 5.2 Real-time Debugging via Serial Interface 5.2.1 Preparing the Application 5.2.2 Configuring HyperTerminal 5.2.3 Using the Serial Debugger

27
27 28 31 32 35 36 37 39

Appendices
A The Integrated Debugger Explained B Installing the USB-to-Serial Cable Driver C Identifying PC Communications Port Used D Setting the Comms Port for the Flash Programmer E Using Code::Blocks to Build Custom Libraries

41
41 43 44 45 47

JN-UG-3028 v1.8

Jennic 2008

Jennic
About this Manual

CodeBlocks IDE User Guide

This User Guide is designed to help you use the Code::Blocks IDE (Integrated Development Environment) to develop applications for devices in the Jennic wireless microcontroller family. The guide focuses on tasks required to implement applications on Jennic devices and does not cover all the features and functionality of Code::Blocks.

Caution: This User Guide refers to Jennics version of Code::Blocks. It should not be used in conjunction with any other version of Code::Blocks.

Organisation
This manual consists of five chapters and five appendices, as follows: Chapter 1 provides a brief overview of using the Code::Blocks IDE. Chapter 2 provides a quick start to using Code::Blocks by describing how to use the IDE to open and build example applications supplied by Jennic. Chapter 3 describes how to create and build your own Code::Blocks projects, and provides advice on dealing with compilation errors. Chapter 4 describes how to download your executable code to the Flash memory of the Jennic wireless microcontroller. Chapter 5 explains how to debug your application with the help of Code::Blocks. The appendices describe the operation of the integrated debugger, how to install the USB-to-serial cable driver, how to identify the PC communications port allocated to a network connection, how to set the PC communications port for the integrated Flash programmer and how to build a custom library in Code::Blocks.

Note: Once you have installed and configured Code::Blocks, you are advised to practise using the IDE with the example applications (as described in Chapter 2) before creating and building your own projects.

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Conventions
Files, folders, functions and parameter types are represented in bold type. Function parameters are represented in italics type. Code fragments are represented in the Courier typeface.

Acronyms and Abbreviations

IDE SDK Integrated Development Environment Software Developers Kit

Related Documents
[1] [2] Jennic Software Developers Kit Installation Guide (JN-UG-3035) Jennic JN51xx Flash Programmer Application User Guide (JN-UG-3007)

Feedback Address
If you wish to comment on this manual, or any other Jennic user documentation, please provide your feedback by writing to us (quoting the manual reference number and version) at the following postal address or e-mail address: Applications Jennic Ltd Furnival Street Sheffield S1 4QT United Kingdom [email protected]

JN-UG-3028 v1.8

Jennic 2008

Jennic

CodeBlocks IDE User Guide

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

1 Overview
For developing applications in an IDE (Integrated Development Environment), Jennic recommends the use of Code::Blocks. This is a full-featured, open source IDE which is available free-of-charge. When developing applications for the Jennic wireless microcontrollers, you should use the specially adapted version of Code::Blocks available from Jennic. This version of Code::Blocks is available as part of the Jennic Software Developers Kit (SDK) Toolchain (JN-SW-4031), but may be selected as an individual option. Installation instructions are provided in the Jennic SDK Installation Guide (JN-UG-3035). The Jennic SDK Toolchain installer and the Installation Guide are available on the: Jennic evaluation kit CDs Support area of the Jennic web site (www.jennic.com/support) This manual describes how to: Create a Code::Blocks project for your application Edit your application code, as required, using the Code::Blocks editor Build your application, to produce a binary file Download your binary file to the device that is to run the application Use Code::Blocks in debugging your application code

Note: Before creating and building your own projects, you are recommended to follow the instructions in Chapter 2 to practise using Code::Blocks with the example applications available on the Jennic web site.

JN-UG-3028 v1.8

Jennic 2008

Jennic

CodeBlocks IDE User Guide

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

2 QuickStart to Using Code::Blocks

This chapter provides a quick start to using Code::Blocks through the example applications available from Jennic.

Note: You are advised to practise using Code::Blocks with the examples before you use the IDE with your own applications.

2.1 Example Applications

Example applications are available for download from the Support area of the Jennic web site (www.jennic.com/support). The examples can be found under Application Notes. For each example application, the source application code and an accompanying note are contained in a ZIP file.

Important: In order to build the software provided with an Application Note, the applications folder must be placed directly under: C:\Jennic\cygwin\jennic\SDK\Application The above directory is automatically created when you install the latest Jennic Software Developers Kit (SDK). You can obtain the latest versions of the SDK libraries and SDK toolchain from the Support area of the Jennic web site (www.jennic.com/support). The relevant part codes are JN-SW-4030 for the SDK libraries and JN-SW-4031 for the SDK toolchain.

JN-UG-3028 v1.8

Jennic 2008

Jennic
2.2 Opening and Building an Example Project

CodeBlocks IDE User Guide

Once you have downloaded an example application from the Jennic web site: Step 1 Unzip the example application into the directory C:\Jennic\cygwin\jennic\SDK\Application The application folder created should be located directly under \SDK\Application. The top level of the applications folder contains a .cbp file for each possible target device type (JN5121 or JN5139) - this is the Code::Blocks project file for the application. Step 2 Step 3 Run Code::Blocks. Open the appropriate .cbp project file (for the target device type) by following the menu path File>Open and browsing for the file. The .c source file and any other files specified in the project can now be accessed via the Projects tab of the left pane in the Code::Blocks window (to view the source code, double-click on the .c file). The compiler and paths to use are also defined. Step 4 Check which compiler is set, as follows: a) b) c) Step 5 Step 6 Follow the menu path Project>Build options to display the Project build options screen. Click on the project name at the top of the tree displayed in the left pane of the screen. Check the Selected compiler field this should show the JN51xx Compiler. If not, select it from the drop-down list.

Make any required edits to the code, using Code::Blocks as the editor. Build the example by following the menu path Build>build. A .bin file is generated and output to a sub-directory that is created by the build process and called JN5121_Build or JN5139_Build, depending on the target device.

Note: To download the .bin file to the target device, refer to Chapter 4.

10

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

3 Creating and Building Your Own Projects

This chapter describes how to create and then build your own applications. It is assumed that you have installed Code::Blocks as described in Chapter 0. Before working on your own applications, you are recommended to practise using the IDE with the example projects provided by Jennic, as described in Chapter 2.

Note: The Jennic installation of Code::Blocks puts a file called default.conf on the C drive of your computer, in the directory Documents and Settings\<user>\Application Data\ codeblocks. This file is used to pre-configure the JN51xx Compiler with the appropriate program files and paths.

3.1 Code::Blocks Projects

In Code::Blocks, an application under development is termed a project. In order to develop an application, you must first create a project for it. This involves creating a project directory.

Note: Jennic have simplified the project creation process by providing a wizard which can be selected when project creation is first entered. As part of the project creation process, Code::Blocks creates a project file, with extension .cbp. This is put into the project directory, along with the C source file(s). The project file contains essential project information, such as all required directory paths and the compiler to use for building the application. Once created, a project can be displayed and manipulated in the Projects tab in the Management pane on the left of the Code::Blocks window. The rest of this chapter describes: How to create a Code::Blocks project (see Section 3.2) How to work on a project in Code::Blocks (see Section 3.3) How to build a project (see Section 3.4)

JN-UG-3028 v1.8

Jennic 2008

11

Jennic
3.2 Creating a Project
To create your own project: Step 1 Step 2 In Code::Blocks, follow the menu path File>New>Project. This displays the New from template screen.

CodeBlocks IDE User Guide

In this screen, select the Jennic icon and then click Go. This starts the Jennic project wizard.

Step 3

In the first screen of the wizard, simply click Next (and, if desired, tick the checkbox Skip this page next time).

12

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic
In the Project title field, enter a name for your project (this is used to create the project filename see Substep c below). In the field Folder to create project in, navigate to the appropriate directory as follows: If you are using the latest Jennic SDK version, the project area is normally C:\Jennic\cygwin\jennic\SDK\ If you are using an earlier Jennic SDK version, the project area may be C:\Jennic\cygwin\jennic\developer\

Step 4

In the next screen, enter your project information as follows: a) b)

c) d)

The remaining two fields (Project filename and Resulting filename) are filled in automatically by the wizard leave them unchanged! Click Next.

JN-UG-3028 v1.8

Jennic 2008

13

Jennic
Step 5 Step 6 In the next screen, select the JN51xx Compiler and click Next.

CodeBlocks IDE User Guide

Now select the environment in which you will work on the application: If you are using the latest Jennic SDK version, you will normally work in the SDK directory: C:\Jennic\cygwin\jennic\SDK\ If you are using an earlier Jennic SDK version (from a JN5121 evaluation kit), you may work in the developer directory: C:\Jennic\cygwin\jennic\developer\ Then click Next.

14

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Step 7

In the next screen, choose the application type. The following are always presented: IEEE 802.15.4 application ZigBee End Device ZigBee Co-ordinator ZigBee Router If you have installed the Jenie software patch (JN-SW-4029), the following will also be presented: Jenie End Device Jenie Co-ordinator Jenie Router Jenie-ZigBee End Device Jenie-ZigBee Co-ordinator Jenie-ZigBee Router The Jenie options are used for Jenie running on JenNet, and the Jenie-ZigBee options are used for Jenie running on ZigBee. Then click Next.

Step 8

Now select the type of board to which the application will be downloaded, from the following: DK1 board (from JN5121-EK000 or JN5121-EK010 evaluation kit) DK2 board (from JN513x-EK000 or JN513x-EK010 evaluation kit) NTS (Network Test System) board High-Power Development Kit board Then click Next.

JN-UG-3028 v1.8

Jennic 2008

15

Jennic
Step 9

CodeBlocks IDE User Guide

In the next screen, select the type of Jennic wireless microcontroller on which you will run the application, from the following (your chip type is marked on the chip or module): JN5121 JN513x (select this option for the JN5139) JN513xR1 (select this option for the early version of the JN5139) Finally, click Finish. Your project has been created!

Note: A Code::Blocks project file (with extension .cbp) has been created in the directory C:\Jennic\cygwin\jennic\SDK\<project name> or C:\Jennic\cygwin\jennic\developer\<project name>

16

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

3.3 Working On Your Project

Once you have created your project, you can work on your application using Code::Blocks as the editor. To edit your code, follow the procedure below: Step 1 If the required project is not already open (if it has been closed since it was created), open the project by following the menu path File>Open and browsing for the relevant .cbp project file. This file should be located in the directory C:\Jennic\cygwin\jennic\SDK\<project name> or C:\Jennic\cygwin\jennic\developer\<project name> Step 2 Click on the Projects tab in the Management pane (on the left of the Code::Blocks window). Your project should appear in the list of projects under Workspace. Step 3 Step 4 Follow the tree structure for your project until you reach the .c file under sources. Note that the .c filename does not initially reflect the name of your project. If required, rename the .c source file, as desired, by right-clicking on it in the Projects tab and selecting Rename file from the pop-up menu. The Rename file screen appears enter the new filename and then click OK.

!
Step 5

Caution: You must rename the .c source file before saving it. Once the file has been saved, the rename option is removed.

To display the code in the main pane, double-click on the .c source file in the Projects tab. You can now edit the code in the main pane. When you have finished editing the .c source file, ensure that you save your changes (for example, by following the menu path File>Save) and then close the file (for example, by following the menu path File>Close file). You are recommended to save your changes regularly while editing. Once you have finished working on the project, save the project changes (for example, by following the menu path File>Save project) and close the project (for example, by following the menu path File>Close project).

Step 6

Step 7

JN-UG-3028 v1.8

Jennic 2008

17

Jennic
3.4 Building Your Project

CodeBlocks IDE User Guide

This section describes how to prepare for and perform an application build. It also provides advice on dealing with compilation errors.

3.4.1 Specifying Paths

Before building your application, ensure that you have specified all the necessary directory paths for the linker and compiler. To do this: Step 1 Step 2 Follow the menu path Project>Build options. The Project build options screen is displayed. Click on the project name at the top of the tree displayed in the left pane of the screen, and then click on the Directories tab to obtain the view shown below.

Step 3

Click on the Compiler sub-tab and ensure that the paths to all the required header files are listed. If you need to add a directory path, use the Add button to specify the new path.

18

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Step 4

Click on the Linker sub-tab and ensure that the path to the linker command file is set as follows: If you are working in the SDK directory, the appropriate path depends on the target device type: For the JN5139: C:\Jennic\cygwin\jennic\SDK\Chip\JN513x\Build For the JN5139R1 (early version of JN5139): C:\Jennic\cygwin\jennic\SDK\Chip\JN513xR1\Build For the JN5121: C:\Jennic\cygwin\jennic\SDK\Chip\JN5121\Build If you are working in the developer directory, the appropriate path is: C:\Jennic\cygwin\jennic\developer\Build.

Step 5

Click on the Linker tab (top-level) to obtain the view shown below.

Step 6

Ensure that the paths to all the necessary link libraries are present in the Link libraries field. If you need to add a directory path, use the Add button to specify the new path. Click OK to register any changes and to exit the Project build options screen.

Step 7

JN-UG-3028 v1.8

Jennic 2008

19

Jennic
3.4.2 Performing a Build

CodeBlocks IDE User Guide

!
Step 1

Caution: Before attempting to build your application, make sure you have specified all the necessary paths for the linker and compiler, as described above in Section 3.4.1.

To build a finished project: If the required project is not already open then open the project by following the menu path File>Open and browsing for the relevant .cbp project file. This file should be located in the directory C:\Jennic\cygwin\jennic\SDK\<project name> or C:\Jennic\cygwin\jennic\developer\<project name> Step 2 Step 3 Click on the Projects tab in the Management pane (on the left of the Code::Blocks window), then browse to and click on the project to be built. Select the required build type, Debug or Release, by following the menu path Build>Select target. If you are building for debug purposes, select Debug If you are building for a final release, select Release Alternatively, you can make this choice using the Build target drop-down list in the Code::Blocks toolbar. Step 4 Build the project (for example, by following the menu path Build>build). The resulting binary file is output to a sub-folder of the project folder, as follows: If you are working in the SDK directory path, the output sub-folder is created during the build process and called JN5121_Build or JN5139_Build, depending on the target device. If you are working in the developer directory path, the output sub-folder is Build. In either case, depending on the build type (Debug or Release), the binary file is put in a further sub-folder called Debug or Release.

Note: During the build, log messages are displayed in the Build log and Build messages tabs of the Messages pane at the bottom of the Code::Blocks window.

20

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

3.4.3 Dealing with Compilation Errors

When the Build>Build or Build>Rebuild menu commands are invoked, the JN51xx Compiler is used to generate a .bin file. If the compiler encounters any errors, the compilation is stopped and error messages are displayed in the Build log tab in the Messages pane at the bottom of the Code::Blocks window. The line where the compiler found the error is marked in the code in the main pane. When interpreting errors, the following points are worth noting: If the error is caused by the omission of a semi-colon or comma then the fault is usually in the line above the line indicated. If the error is generated by the linker then the message will often refer to a function name preceded by an underscore; e.g. _vAHI_DioSetDirection. This would suggest that a required file is missing in the project or a file cannot be found on the specified path. To include a specific file, follow the menu path Project >Add files and add the file into the project. Once you have corrected any errors, use Build>Rebuild to re-build your project.

JN-UG-3028 v1.8

Jennic 2008

21

Jennic

CodeBlocks IDE User Guide

22

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

4 Downloading an Application Binary

Once you have built your project, you must download the binary output to the Flash memory in the wireless microcontroller of the device that is to run the code. This chapter outlines how to perform the download.

4.1 Pre-requisites
Ensure that you have the following: A target device containing a Jennic wireless microcontroller. A serial cable and dongle allowing connection between your PC and the target device. The .bin file to be downloaded following a build, this file is placed in the Build\Release or Build\Debug directory for the project, as appropriate.

4.2 Download Procedures

You must use a Flash programmer to download your applications binary file to the Flash memory of the JN51xx on the target device. If you wish to use the Flash programmer (optionally) integrated into Code::Blocks, refer to Section 4.2.1. If you wish to use a separate installation of the JN51xx Flash Programmer, refer to Section 4.2.2.

JN-UG-3028 v1.8

Jennic 2008

23

Jennic
4.2.1 Using the Integrated Flash Programmer

CodeBlocks IDE User Guide

The version of Code::Blocks provided by Jennic includes the possibility of an integrated Flash programmer that allows you to download your binary file to the target device from within Code::Blocks. To use this facility, you must have opted to install it during the installation process. To download your .bin file to a device: Step 1 Step 2 Connect a USB port of your PC to the target device (if prompted to install the device driver for the USB-to-serial cable, refer to Appendix B). In Code::Blocks, follow one of the following menu paths, depending on whether you wish to initiate the download from a GUI (Graphical User Interface) or from the command line:

Note: You will need to set the PC communications port that has been assigned to the connection to the target device to identify this port, refer to Appendix C. If you are going to work from the command line and need to use a PC comms port other than port 1 (the default), refer to Appendix D for details of how to set a port. Tools>Flash GUI The following JN51xx Flash Programmer GUI window is displayed:

24

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Tools>Download to Flash You must select the command line option according to the target device and the build type (Debug or Release). The following command window is displayed:

Step 3

Reset the device and put it into programming mode. To do this on boards/modules from kits JN5139-EK000, JN5139-EK010 and JN5139-EK020: a) b) c) Press and hold down the Programming button on the board/module. Press and then release the Reset button on the board/module. Release the Programming button.

Important: For boards from kits JN5121-EK000 and JN5121EK010, reset the board by switching it OFF and then ON again (alternatively, on Controller boards, you can use the Reset button). These boards are automatically put into programming mode when the Flash programmer starts and asserts the RTS line, which is connected to the SPi-bus MISO line. Step 4 To start the download, perform either of the following actions, as appropriate: Browse for the binary file in the GUI window and then click the Program button. Make sure you are in the command window and then press the Enter (or Return) key on your keyboard. Step 5 Once the download has finished, disconnect the device from the PC and powercycle the device.

JN-UG-3028 v1.8

Jennic 2008

25

Jennic
4.2.2 Using a Separate Flash Programmer

CodeBlocks IDE User Guide

If you wish to use a separate installation of the JN51xx Flash Programmer, refer to the procedure for downloading binary code in the Jennic JN51xx Flash Programmer Application User Guide (JN-UG-3007).

26

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

5 Debugging Application Code

This chapter describes the available methods for debugging your application code. There are two possible approaches to debugging: Using the Code::Blocks integrated debugger Code::Blocks incorporates GDB (GNU project debugger). This integrated debugger provides an easy-to-use debugging method from Code::Blocks. Using the integrated GDB debugger, you can: Run to a breakpoint or cursor position Watch local variables Single-step, and step into and out of functions Note that the GDB debugger does not allow you to: debug into library API code (compiled with optimisation); watch global variables (incompatibility between compiler and GDB); debug interrupts (GDB controls interrupts during a breakpoint); stop the underlying hardware timers and integrated peripherals. Use of the integrated debugger is described in Section 5.1. Using the serial UART to send debugging messages to a terminal When debugging network applications in real-time, we suggest that you use the UART to send text messages to a terminal program, such as HyperTerminal, running on a PC. This involves embedding debug print-toUART code segments in the main code of your application. This method is described in Section 5.2.

5.1 Using the Integrated Debugger

Code::Blocks incorporates GDB (GNU project debugger). The sub-sections below describe how to configure and use this debugger. Further operational information on the GDB debugger is provided in Appendix A.

Caution: When debugging code using the integrated debugger, you are recommended to disable any compiler optimiser settings, otherwise the debugger may not operate correctly. For more information, refer to the tip on page 35.

JN-UG-3028 v1.8

Jennic 2008

27

Jennic
5.1.1 Configuring the Integrated Debugger

CodeBlocks IDE User Guide

The procedure below describes how to configure the integrated debugger. Step 1 Step 2 Step 3 Step 4 Connect a USB port of your PC to the target device (if you are prompted to install the device driver for the USB-to-serial cable, refer to Appendix B) Start Code::Blocks (if not already started). Follow the menu path Settings>Compiler and debugger. This displays the Compiler and debugger settings screen. Select the Debugger settings icon from the left panel and fill in the dialogue box as follows: a) Update the following lines in the Debugger initialisation commands field:
set remotebaud 9600 target remote /dev/ttyS2

Note that this assumes you will use a baud rate of 9600 bps. However, you can use a different baud rate, if you wish see Section 5.1.3. It also assumes you will use serial communications port COM3 for debugging. If you need to use a different serial port, change x in /dev/ttySx accordingly (note that COM1 corresponds to ttyS0, COM2 to ttyS1 and so on). You can identify the serial port that has been allocated to the connection with the target device as described in Appendix C. b) If necessary, also update the source code paths in the Debugger initialisation commands field. For example, if the source files are stored in the folder Source_v1, modify the dir lines to:
dir ..\Source_v1 dir ..\..\Source_v1

c) d)

Ensure that the checkbox Do not run the debugee (program to be debugged) is selected. In the area Choose disassembly flavor (GDB only), from the drop-down list select Custom (specify instruction set) and in the right field enter or32. This screen should then look like the screenshot below.

28

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Step 5 Step 6

Select the Global compiler settings icon from the left panel and then in the Selected compiler field, ensure that the JN51xx compiler is selected. Select the Programs tab and then the Program Files sub-tab, and set the Debugger field to ba-elf-gdb.exe. This screen should then look as shown in the screenshot below.

JN-UG-3028 v1.8

Jennic 2008

29

Jennic

CodeBlocks IDE User Guide

Step 7 Step 8

Select the Compiler tab and then the Compiler Flags sub-tab, and ensure that the checkbox Produce debugging symbols [-g] is ticked. Click on OK to register all changes and leave the Compiler and debugger settings screen.

30

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

5.1.2 Operating the Integrated Debugger

This section outlines how to debug an application with the integrated debugger. The procedure below assumes that you have an application program to debug and an associated Code::Blocks project file. Step 1 Step 2 Start Code::Blocks and open the Code::Blocks project file (.cbp) for the application to be debugged. Ensure that your code includes the following lines (which initialise the debugger and cause it to halt, once it has started). a) Include the header file gdb.h, as follows:
#include "gdb.h"

b)

Add the following as the first few lines of the function AppColdStart() or, in the case of a Jenie application, the function vJenie_CbInit():
#ifdef GDB /* Debug hooks: include regardless of whether debugging */ HAL_GDB_INIT(); HAL_BREAKPOINT(); #endif

Step 3

In Code::Blocks, ensure that optimisation is OFF in Project>Build options and that the defines in your project build options include "GDB". If your application is based on an example provided by Jennic or generated using the New Project wizard, this should have already been done. Build the application for a Debug target, as described in Section 3.4. Download the resulting debug binary file to the device which is to run the application, using the Jennic Flash programmer as described in Section 4.2. Once the download has completed, close the Flash programmer in order to release the serial port for the debugger to use (otherwise, GDB will not be able to access the serial port). Open the Watch window by following the menu path Debug>Debugging Windows>Watches. Set the desired breakpoints by right-clicking on the required line and selecting Toggle breakpoint from the menu. A red dot then appears next to the line number. Do this for as many breakpoints as you need. Reset the target device. This puts the target device under the control of GDB and enables Code::Blocks to control the device. Start the debugger by following the menu path Debug>Start or clicking on the Debug/Continue icon. There will be a short pause before the debugger is ready for use. A yellow arrow appears on the source display to show the current debug position in the code - this should be the default GDB breakpoint, HAL_BREAKPOINT.

Step 4 Step 5 Step 6

Step 7 Step 8

Step 9 Step 10

JN-UG-3028 v1.8

Jennic 2008

31

Jennic
Step 11 Start debugging by performing the following actions, as appropriate:

CodeBlocks IDE User Guide

Use Run to cursor, Single step (and other options), as appropriate. To watch any local variables, click on the '+' to open the tree in the Watch window. To end the debugger session, follow the menu path Debug>Stop Debugger. Once the debugger session has been stopped, to run the debugger again go back to Step 9 and continue from there. Practical advice on using the integrated debugger is provided in the next section.

5.1.3 Tips on Using the Integrated Debugger

This section provides useful tips on using the Code::Blocks integrated debugger. Setting the baud rate By default, the baud rate for the debugger serial connection is 9600. However, it is configurable using the function vAHI_UartSetClockDivisor(), allowing you to change the speed of the JN51xx debug port, if desired. The code fragment from Step 2b in Section 5.1.2 is repeated below with the addition of the above function to set the baud rate to 38400.
#ifdef GDB /* Debug hooks: include regardless of whether debugging */ HAL_GDB_INIT(); vAHI_UartSetClockDivisor(0,E_AHI_UART_RATE_38400); HAL_BREAKPOINT(); #endif

Note that changing the baud rate in your code, as described above, modifies the baud rate of the UART on the JN51xx device. You must also change the PC baud rate in Code::Blocks, as described in Section 5.1.1. In addition to E_AHI_UART_RATE_38400 (for 38400 bps), other enumerations are available for different baud rates. These are defined in the header file AppHardwareApi.h and listed in Table 1 below.

32

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic
Baud Rate (bps) 4800 9600 19200 38400 76800 115200 Enumeration E_AHI_UART_RATE_4800 E_AHI_UART_RATE_9600 E_AHI_UART_RATE_19200 E_AHI_UART_RATE_38400 E_AHI_UART_RATE_76800 E_AHI_UART_RATE_115200 Value 0 1 2 3 4 5

Table 1: Enumerations for UART Baud Rates

Caution: The baud rate of 9600 will work for all JN51xx devices and developer platforms. As the baud rate is increased, the debug system may fail due to platform variations. In this case, you are recommended to use a lower baud rate, or the default 9600 bps.

Preventing Watchdog timer operation during debug All watchdog hardware timers will continue to run while the debugger is held at a breakpoint and could timeout, forcing a reset. This gives the impression that the debugger is not running correctly the cursor will jump back to HAL_BREAKPOINT, giving the appearance that no debug progress is being made. To avoid this situation, watchdog operation must be prevented during debug this is achieved with a conditional compile around the watchdog timer instruction, implemented using a GDB define, as shown in the following example:
#ifndef GDB /* Initialise and start the watchdog */ InitWatchDogTimer(); #endif

Preventing the use of UART0 during debug The integrated debugger uses UART0. Therefore, you must not use UART0 for other purposes during debug. This can be achieved by including any actions that involve UART0 in a GDB define, as in the following example:
#ifndef GDB /* Comms activity on UART0 */ PrintToComm0("test"); #endif

JN-UG-3028 v1.8

Jennic 2008

33

Jennic
Setting correct compiler options for migrated projects

CodeBlocks IDE User Guide

If a Code::Blocks project has been migrated from an earlier version of Code::Blocks then you must ensure that the correct compiler options have been set for the latest compiler, otherwise you may get unexpected debugger behaviour such as not recognising line numbers or not stepping through the code correctly. If your compiler settings are incorrect, you will obtain messages in the Debugger window similar to those shown below.

For an explanation of how to update the project so that all the compiler and linker settings are correct, refer to the Application Note Migrating Projects to Upgraded SDK (JN-AN-1053). Bringing device out of reset so that debugger can start The serial cable connection can occasionally hold the device in reset, so the debugger does not start. To resolve this issue: 1. Disconnect the serial cable from the device. 2. Reset the device. 3. Reconnect the serial cable to the device. 4. In Code::Blocks, start the debugger by following the menu path Debug>Start or clicking on the appropriate debugger icon. Using the Debug button (rather than the Run button) The Run button and the Build and run button attempt to execute the binary on the PC rather than on the JN51xx target device. To execute the binary on the JN51xx device, use the Debug button or the menu option Debug>Start (see Section 5.1.2). If you attempt to run debug code on the PC, you will obtain the following error message:

34

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Disabling optimisation for debug When debugging code using the integrated debugger, you are recommended to disable any compiler optimiser settings. When the compiler optimiser is invoked, it uses a variety of techniques to optimise for size or speed (as specified by the user). Optimisation techniques vary depending on the compiler being used, but can involve unwinding loops, saving variables in registers, delaying variable initialisation, and in-lining small or rarely used functions. All these tasks take the code generation away from the 'ideal case' and, as a result, make it difficult for the debugger to map the progress of the processor back onto the user source code. This can give the appearance that the code is misbehaving. Depending on the degree of optimisation used, the yellow run cursor can appear to move randomly around the lines in the source code window, variables can appear to have the wrong values and stack traces can appear corrupt.

5.2 Real-time Debugging via Serial Interface

This section describes how to debug real-time network applications using the JN51xx devices serial UART to output debug information to HyperTerminal running on a PC. In this case, Code::Blocks is used to generate the code that is run, but does not have a role in the debug process. vPrintf, which is a small memory footprint version of printf, is used to send formatted debugging text from the application to the UART. This reduced version of printf is limited to the following commands: %d - show a decimal value %x - show a value in hex %b - show a value in binary %c - show a character %s - show a string %% - show a % character The vPrintf source and include files can be found in the directory SDK\Chip\Common\. In the example presented in the sub-sections below, the debug serial text is sent via UART0, which is also used for the Flash programmer.

JN-UG-3028 v1.8

Jennic 2008

35

Jennic
5.2.1 Preparing the Application

CodeBlocks IDE User Guide

You must first prepare your application source code, as described in the procedure below. Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Load the project to be debugged into Code::Blocks. Check that the build target is Release by following the path Build>Select target. Add the library vPrintf files using Project>Add Files. Select SDK\Chip\Common\Source\Printf.c. Click the checkboxes for both the Release and Debug builds. Add the library vPrintf files using Project>Add Files. Select SDK\Chip\Common\Include\Printf.h. Click the checkboxes for both the Release and Debug builds. Add the following code to the source file under test. Include the Printf.h header file:
#include "..\..\..\Chip\Common\Include\Printf.h"

Initialise the UART during the hardware initialisation

/* Initialise serial comms unless debug mode*/ #ifndef GDB vUART_printInit(); #endif

Add debug lines wherever they are required; for example:

vPrintf("\n\r\n\rAddress = %x", u16NodeId);

Note: \n\r is used to provide CR LF in the terminal emulator. Step 8 Step 9 Step 10 Step 11 Build the project for Release, as described in Section 3.4. Connect the Flash programmer, via the serial cable, to UART0 on the target device. Using the Flash programmer, download the application binary to the target device. Close the Flash programmer (otherwise it will hold the serial port open).

Note: You must connect/disconnect after each session in order to use the Flash programmer. Alternatively you can use Brays free Terminal v1.9 - this utility detects if another program is using the port and will automatically disconnect if you tick the Auto Dis/Connect box (www.hw-server.com/software/termv19b.html).

36

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

5.2.2 Configuring HyperTerminal

This section describes how to configure HyperTerminal for real-time debugging via a serial interface. Step 1 Open HyperTerminal by the following the Windows Start menu path All programs>Accessories>Communications>HyperTerminal.

Note: If no modem has been configured on the PC, you may get screens requesting the location. Ignore these screens. Step 2 Access the New Connection screen by following the menu path File>New Connection. Type a name for the connection, then click OK.

The next screen, Connect To, is then displayed.

JN-UG-3028 v1.8

Jennic 2008

37

Jennic
Step 3

CodeBlocks IDE User Guide

In the Connect To screen, choose the serial communications port that the board is connected to and then click OK.

The next screen, COM Properties, is then displayed. Step 4 In the COM Properties screen, set the port properties to 19200 bits per second, 8 data bits, no parity, 1 stop bit and no flow control, then click OK.

The terminal connects to the communications port and the HyperTerminal screen is displayed.

38

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

5.2.3 Using the Serial Debugger

Run the target software by resetting the host device. The debugging trace will then appear on the HyperTerminal screen. The terminal could also be used to send commands to the target in order to test its operation. This would require the addition of an interrupt handler to process the received commands. An example of handling serial data is provided in the Application Note Serial Cable Replacement using 802.15.4 (JN-AN-1005).

JN-UG-3028 v1.8

Jennic 2008

39

Jennic

CodeBlocks IDE User Guide

40

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Appendices
A The Integrated Debugger Explained
This appendix explains the operation of the integrated GDB debugger. What is GDB? GDB (GNU project debugger) is a general-purpose debugger that can be used to debug applications written in C, C++, Pascal and Fortran, amongst other languages. The debugger is available (free-of-charge) as part of the well-known GNU toolkit and is used through a text-based interface here, this interface is provided by Code::Blocks. One of the main features of the GDB debugger is its facility for remote debugging that is, it allows you to debug code running on one platform from another platform (running GDB). For example, an application running on a microcontroller device can be debugged from a PC running GDB. In this case, the two platforms are connected via a serial port, a network link or some other method. This capability is utilised when debugging code running on a Jennic JN51xx wireless microcontroller, allowing you to step through code, set breakpoints and view memory contents, as well as generally interact with the microcontroller. The main disadvantage of the GDB debugger is that it is not easily adapted to embedded real-time environments, since GNU components were initially designed for developing desktop applications in Unix-type environments. How does GDB operate? For remote debug (as used for the JN51xx device), GDB interacts with the target application via a debug stub, which is a small, intermediate application compiled into the target system. Communication between GDB and the debug stub is implemented using the GDB Remote Serial Protocol this is an ASCII messagebased command set which supports tasks that include reading/writing from/to memory, querying registers and running the application under test. Jennic's debug stub is activated using the macro HAL_GDB_INIT. The debugger deals with setting and processing a breakpoint in the following way: 1. When a breakpoint is set, GDB employs memory read/write commands to non-destructively replace a source instruction with a TRAP instruction. 2. When the instruction is reached during execution, control is transferred from the processor to the debug stub. 3. The debug stub notifies GDB that a breakpoint has been encountered. The user can now interact with the hardware, as required. 4. GDB sends a command corresponding to the required action to the debug stub. 5. Once the breakpoint has been dealt with, the debug stub returns control to the processor.
JN-UG-3028 v1.8 Jennic 2008 41

Jennic
What happens during a breakpoint on the JN51xx?

CodeBlocks IDE User Guide

When a breakpoint is reached, the debug stub is invoked on the JN51xx target. The stub then services any requests and commands received from the GDB host. GDB stalls any application code that was running on the device processor before the breakpoint was encountered.

Note: During a breakpoint, only the JN51xx CPU is stalled. The JN51xx integrated peripherals still run normally, with timers running and expiring, network packets arriving and the integrated peripherals free to generate interrupts. What happens after a breakpoint on the JN51xx? When you instruct GDB (via the Code::Blocks IDE) to step out of the breakpoint, the CPU interrupt handler processes all other queued interrupts generated during the period of the breakpoint. Therefore, any timer interrupts, network packets and analogue peripheral interrupts that have occurred during this period are processed. Control is then returned to the processor, resuming application execution.

Note: Application data and peripheral hardware status may have changed during the breakpoint period. The processing of queued interrupts may alter buffer contents and update program variables. Understanding this is key to explaining any unexpected behaviour in the application while it is being debugged. Where can I get more information on GDB? The following are useful web links to further information on GDB: For a more detailed description of using GDB in an embedded environment: http://www.embedded.com/1999/9909/9909feat2.htm For an excellent guide to GDB: http://www.dirac.org/linux/GDB/ For detailed manuals on GDB: http://docs.freebsd.org/info/GDB/GDB.pdf http://wwwcdf.pd.infn.it/localdoc/GDBint.pdf

42

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

B Installing the USB-to-Serial Cable Driver

The USB-to-serial cable supplied with Jennic evaluation and starter kits allows a PC USB port to be used as a serial communications port and requires an FTDI driver. This driver is provided in the Jennic SDK Toolchain and on the starter kit CD, and must be installed on your PC the first time you use the supplied cable for example, when downloading binary code from a PC to a board. This installation is described below (although you may not need this procedure if Windows automatically finds the required driver on the Internet). 1. When you plug the USB-to-serial cable into a USB port of your PC, check whether Found new hardware wizard for TTL232r-3v3 is displayed. If this appears, you must install the driver by following the rest of this procedure. Otherwise, the driver is already installed. 2. Fill in the screen Install from a specific location, as follows: a) Select the radio button Search for the best driver in these locations. b) Tick the checkbox Include this location in the search. c) Using the Browse button, navigate to the directory FTDI_drivers, either in the installed SDK on your PC or on the starter kit CD. For example, if the SDK has been installed on drive C of your PC, the required path will be: C:\Jennic\drivers\FTDI_drivers d) Click OK. The wizard will automatically fill in the details in the drop-down search box. 3. In the Found new hardware wizard screen, click Next. 4. Wait for the wizard as it searches for and installs the new driver. On completion, it will display the message Completing the Found new hardware wizard. Click Finish to complete. In some cases, you may need to repeat the procedure from Step 2, depending on your hardware configuration. Finally, the Found new hardware bubble will indicate that the hardware is installed and ready for use.

Note: Alternatively, you can obtain the relevant driver for your operating system from the FTDI web page www.ftdichip.com/FTDrivers.htm. Go to the VCP drivers, download the required driver to your desktop and double-click on its icon to install.

JN-UG-3028 v1.8

Jennic 2008

43

Jennic
C Identifying PC Communications Port Used

CodeBlocks IDE User Guide

When connecting your PC to a board, you need to find out which serial communications port your PC has allocated to the connection, as described below. 1. In the Windows Start menu, follow the menu path: Start>Control Panel>System This displays the System Properties screen. 2. In the System Properties screen: a) Select the Hardware tab. b) Click the Device Manager button This displays the Device Manager screen. 3. In the Device Manager screen: a) Look for the Ports folder in the list of devices and unfold it. b) Identify the port which is connected to the board (it will be labelled USB Serial Port) and make a note of it (e.g. COM1).

44

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

D Setting the Comms Port for the Flash Programmer

The integrated Flash programmer allows you to download your binary code to the target device from within Code::Blocks see Section 4.2.1. As well as a GUI version of the Flash programmer, there is a command line version for each target chip and build type (Debug or Release) all versions are accessed via the Tools menu. If you are using a command line version of the Flash programmer and you need to set the PC communications port to be used, follow the procedure below.

Note: For the GUI version of the Flash programmer, you can set the PC communications port from within the GUI itself. Step 1 Step 2 In Code::Blocks, follow the menu path Tools>Configure tools. This displays the User-defined tools dialogue box, containing a list of tools. Select the tool you wish to use (e.g. Download to Flash for JN513x Release) and then click Edit. The Edit tool screen is displayed.

The fields of this screen are pre-filled with the relevant information, as shown above.

JN-UG-3028 v1.8

Jennic 2008

45

Jennic
The fields are briefly as follows:

CodeBlocks IDE User Guide

Name: The name of the tool (e.g. Download to Flash for JN513x Release) to appear in the Tools menu in Code::Blocks. Executable: The path to the executable for the download tool. Parameters: Specifies the name of the binary file to be downloaded and the PC communications port to use. When working on a project, {PROJECT_NAME} is automatically substituted with the Code::Blocks project name. Working directory: Specifies the location of the binary file to be downloaded. {PROJECT_DIR} is automatically substituted with the Code::Blocks project directory. Step 3 In the Parameters field, ensure that the PC communications port setting is as required (in f ${PROJECT_NAME}.bin c1, the 1 is the comms port setting). Change the port number, if needed. Then click OK.

46

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

E Using Code::Blocks to Build Custom Libraries

This appendix describes how to use Code::Blocks to create your own library project and to build the library, with which your application can then be linked. Step 1 In Code::Blocks, create a new project by following the menu path File>New>Project. This displays the New from template screen. Step 2 In this screen, select the Static Library icon and then click Go. This starts the Static Library project wizard.

Step 3

In the first screen of the wizard, simply click Next (and, if desired, tick the checkbox Skip this page next time).

JN-UG-3028 v1.8

Jennic 2008

47

Jennic
Step 4 In the next screen, enter your project information as detailed below.

CodeBlocks IDE User Guide

a) b)

In the Project title field, enter a name for your project (this is used to create the library filename see Substep c below). In the field Folder to create project in, navigate to the development directory in which the library project folder should be created. The required path is normally C:\Jennic\cygwin\jennic\SDK\Application. The remaining two fields (Project filename and Resulting filename) are filled in automatically by the wizard leave them unchanged! Click Next.

c) d)

48

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic

Step 5

In the next screen ensure that the Compiler field shows JN51xx Compiler and then click Finish.

Your library project has been created! Step 6 To include a specific source file in the library, follow the menu path Project >Add files and add the file into the project.

Note: To re-build your library, use Build>Rebuild.

JN-UG-3028 v1.8

Jennic 2008

49

Jennic

CodeBlocks IDE User Guide

50

Jennic 2008

JN-UG-3028 v1.8

CodeBlocks IDE User Guide

Jennic
Date 29-Nov-2006 07-Feb-2007 23-Feb-2007 Description First release Updated to cover both JN5121 and JN513x series devices Corrected paths for new SDK folder structure. Removed basic integrated Flash programmer. Installation chapter removed and download chapter updated for JN513x chip series Updated for R1 of JN5139 device. Added chapter on integrated debugger. Added debugger chapter and appendices Added Jenie to project templates Updated for new SDK installers (JN-SW-4030 and JN-SW-4031). Added procedures to Appendix for connecting a PC to a network node. Added procedure for building custom libraries in Code::Blocks and made other minor modifications

Revision History
Version 1.0 1.1 1.2

1.3

25-Apr-2007

1.4

24-May-2007

1.5 1.6 1.7

24-Oct-2007 26-Nov-2007 06-Mar-2008

1.8

04-Dec-2008

JN-UG-3028 v1.8

Jennic 2008

51

Jennic
Important Notice

CodeBlocks IDE User Guide

Jennic reserves the right to make corrections, modifications, enhancements, improvements and other changes to its products and services at any time, and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders, and should verify that such information is current and complete. All products are sold subject to Jennics terms and conditions of sale, supplied at the time of order acknowledgment. Information relating to device applications, and the like, is intended as suggestion only and may be superseded by updates. It is the customers responsibility to ensure that their application meets their own specifications. Jennic makes no representation and gives no warranty relating to advice, support or customer product design. Jennic assumes no responsibility or liability for the use of any of its products, conveys no license or title under any patent, copyright or mask work rights to these products, and makes no representations or warranties that these products are free from patent, copyright or mask work infringement, unless otherwise specified. Jennic products are not intended for use in life support systems/appliances or any systems where product malfunction can reasonably be expected to result in personal injury, death, severe property damage or environmental damage. Jennic customers using or selling Jennic products for use in such applications do so at their own risk and agree to fully indemnify Jennic for any damages resulting from such use. All trademarks are the property of their respective owners.

Corporate Headquarters Furnival Street Sheffield S1 4QT United Kingdom Tel +44 (0)114 281 2655 Fax +44 (0)114 281 2951 E-mail [email protected] United States Sales Office 1060 First Avenue, Suite 400 King of Prussia PA 19406 USA Tel +1 619 223 2215 Fax +1 619 223 2081 E-mail [email protected]

Japan Sales Office Osakaya building 4F 1-11-8 Higashigotanda Shinagawa-ku, Tokyo 141-0022, Japan Tel +81 3 5449 7501 Fax +81 3 5449 0741 E-mail [email protected] Korean Sales Office 601, Bethel B/D, #324-1 Yangjae-dong Seocho-gu Seoul 137-897 Korea Tel +82 2 552 5325 Fax +82 2 577 9130 E-mail [email protected]

Taiwan Sales Office 19F-1, 182, Sec.2 Tun Hwa S. Road Taipei 106 Taiwan Tel +886 2 2735 7357 Fax +886 2 2739 5687 E-mail [email protected]

52

Jennic 2008

JN-UG-3028 v1.8