Configuring Eclipse for EFM32 Development

This application note explains how to install Eclipse on Windows and set up a simple project. Compiling and debugging the code on an EFM32 microcontroller is demonstrated. All the software components used in this application note come free of charge.

1 Prerequisites

You will need an Energy Micro Starter or Development kit with an EFM32 Cortex-M3 microcontroller.

The zip-file an0023_efm32_eclipse_toolchain.zip that comes with this application note contains the required Eclipse plug-ins and an xml-file that patches older versions of J-Link GDB Server to show the correct CPU registers for Cortex-M3 targets. This zip-file can be zipped directly into the Eclipse install folder.

 

1.1 A note on versions

To succeed in making your setup work, it is important to notice that there are many different tools from different sources involved. The versions shown in Table 1.1 (p. 2) has been tested to work, and it is recommended to use these versions as a starting point. Once the setup is stable, feel free to experiment with newer tool versions.

Microsoft Windows 7 Professional was used to prepare this application note.

These software packages also exists for Linux, and although this application note is Windows specific, the setup procedure should be fairly similar.

Table 1.1. Tool version information

Tool name	Version
Eclipse IDE for C/C++ Developers	Version: 3.7.2 Build id: 20120216-1857 (Indigo)
C/C++ GDB Hardware Debugging plugin for Eclipse	Version: 7.0.0.201202111925
Embedded Systems Register View plugin for Eclipse	0.2.0
Sourcery CodeBench Lite for ARM/EABI	2012.03-56 gcc version 4.6.3 gdb version 7.2.50.20100908-cvs
SEGGER J-Link ARM	V4.36E
Simplicity Studio	n/a

J-Link GDB Server is part of SEGGER's J-Link Software and Documentation Pack that comes with Simplicity Studio. Newer versions can be downloaded from SEGGER. These newer versions don't need the Cortex-M register patch that is included with this application note.

 

1.2 Installing the tools

1.2.1 Simplicity Studio

Download Simplicity Studio from

http://www.energymicro.com/simplicity

and install it.

Launch Simplicity Studio and answer Yes to the question about installing the recommended packages. Answer OK to the question about installing the J-Link drivers.

You will get a directory structure as shown below within your Simplicity Studio work directory at

C:\%APPDATA%\energymicro\

The location of %APPDATA% depends on which version of Windows you are, and the directory is hidden by default. Pay special attention to the blink example as it will be used later in this application note.

Figure 1.1. Energy Micro folder structure

It is now time to connect the kit to your machine via the supplied USB cable and check that the J-Link device driver was properly installed.

From the start menu, launch the program called J-Link GDB Server via SWD found in the SEGGER folder. If everything is OK, the server should be able to connect to the board and the GUI should look something like:

Figure 1.2. J-Link GDB Server GUI

Do not exit this program before continuing.

 

1.2.2 Sourcery CodeBench Lite

Install the Sourcery CodeBench Lite. It is available from:

http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/ editions/lite-edition

Download the EABI Release for ARM processors.

When prompted with a question to add CodeBench to the PATH environment variable, you should accept.

 

1.2.3 Eclipse IDE for C/C++ Developers

As Eclipse is a Java application you must have Java Runtime Environment (JRE) installed on your computer before installing Eclipse. Most computers already hava a Java installation. You can check if Java is installed by visiting:

http://java.com

and click on the link named Do I have Java?, or by issuing the command:

java -version in a command prompt.

Eclipse is available from: http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developersincludes-incubating-components/indigosr2

When downloading Eclipse make sure you select the Windows version. The Indigo (SR2) edition was used in this application note.

Simply unpack the zip file at C:\ and you have a full Eclipse installation at C:\eclipse.

The two plugins needed can be installed from online repositories as described in the following sections, or by extracting an0023_efm32_eclipse_toolchain.zip into your Eclipse install folder. If you elect to use the plugins in the zip file, copy the relevant files into the features and plugins subdirectories under C:\eclipse. This directory structure is replicated inside the zip file.

1.2.3.1 C/C++ GDB Hardware Debugging plugin

Start Eclipse by executing C:\eclipse\eclipse.exe. When prompted for workspace navigate to the examples directory for your kit in Simplicity Studio's working directory. In our case

C:\%APPDATA%\energymicro\kits\EFM32TG_STK3300\examples

You will now be greeted by Eclipse's welcome screen.

Select Install New Software... from the Help pulldown menu. In the Work with field, enter:

http://download.eclipse.org/releases/indigo

You might need to wait a while for the plugins to show up. Browse to Mobile and Device Development and select C/C++ GDB Hardware Debugging. Press Next >, and follow the instructions.

Figure 1.3. GDB Hardware Debugging plugin installation

The installation process may take a while. When asked to restart Eclipse, do so.

1.2.3.2 Eclipse Embedded Systems Register View plugin

Proceed as described in the previous section, but in the Work with field, enter:

http://embsysregview.sourceforge.net/update

Select Embedded Systems Register View, click Next > and restart Eclipse when asked to do so.

Figure 1.4. Embedded Systems Register View plugin installation

 

2 Working with Eclipse

Now it is time to continue with Eclipse. Close Eclipse's welcome screen tab and Eclipse's Workbench view appears:

Figure 2.1. The Eclipse Workbench View

 

2.1 Create a project

The new project will be based on the 'blink' example project for the EFM32TG-STK3300. It is quite simple to follow this procedure to setup a project for another EFM32 device.

Create the project:

1. Select File -> New -> C Project

2. For Project name use blink (same name as the project directory)

3. For Project type select Makefile project

4. For Toolchain select -- Other Toolchain --

5. Click the Finish button to complete the project definition.

Figure 2.2. Create a new project in Eclipse

Add project properties:

1. Select Project -> Properties

2. Expand C/C++ Build

3. Uncheck "Use default build command"

4. For "Build command" type in cs-make

5. Modify Build directory to ${workspace_loc:/blink/codesourcery} Figure 2.3. Eclipse Project Properties - Build

6. Navigate to C/C++ Build -> Discovery Options

7. Uncheck "Automate discovery of paths and symbols"

Figure 2.4. Eclipse Project Properties - Discovery Options

8. Navigate to C/C++ Build -> Settings

9. Check GNU Elf Parser

Figure 2.5. Eclipse Project Properties - Build Settings

Click the OK button to save project properties.

 

2.1.1 Makefile

Some changes also needs to be made to the Makefile. We will want to inspect the Makefile and understand how it is setup and ensure it is setup correctly for our project.

1. Find the Makefile.blink in the blink/codesourcery directory

2. Save it with filename Makefile without a file type suffix

These operations are easily performed by right-clicking on the files in the Project Explorer pane and selecting Copy and Paste. In the Eclipse Project Explorer you should now see a green bullseye next to the Makefile.

Figure 2.6. Makefile location in Eclipse Project Explorer

Open the Makefile inside Eclipse by double-clicking on it in the Project Explorer. Do the following changes:

1. Change the WINDOWSCS variable. It should point to your CodeBench Lite installation relative tothe Program Files folder

WINDOWSCS = CodeSourcery/Sourcery_CodeBench_Lite_for_ARM_EABI

2. Check that the CFLAGS macro contains option -O0. The -O<n> option select code optimization level.Using -O0 makes it easier to use the debugger.

debug: CFLAGS += -DDEBUG -O0 -g3

3. Set the PROJECTNAME macro to the same name as the project root directory

PROJECTNAME = blink

4. Set the DEVICE macro to reflects the EFM32 you use

DEVICE = EFM32TG840F32

In the Makefile you will find the Include paths for header files as well as C source files that are being compiled in the project. When you want to add more functionality from emlib to your project, you have to add the proper path and C source file location to the makefile.

 

2.1.2 Add Eclipse Paths and Symbols

Even though the project will now compile, Eclipse will mark errors. This is because Eclipse is rather separated from the CodeBench GCC toolchain, and Eclipse do not know where the various header files are located. GCC knows this because of the Makefile but these details are not inherited by Eclipse. So we need to tell Eclipse where these files are.

1. From main menu, open Project -> Properties 2. Navigate to C/C++ General -> Paths and Symbols

3. Select Add...

4. Select Add to all configurations and Add to all languages

5. Select File system... to add folders to path

Figure 2.7. Add directory paths

6. Add all the folders from INCLUDEPATH in the Makefile

7. Add the include folders for CodeBench GCC as shown in Figure 2.8 (p. 13)

Figure 2.8. Eclipse Project Properties - Paths and Symbols

 

2.2 Build the code

We are now ready to compile the project. It can be useful to make sure the Console Tab is showing in the bottom of Eclipse so we can see the CodeBench GCC compiler output.

There are multiple ways to build the project. Some are listed below:

• From the main menu, select Project -> Build Project

• From the Project Explorer pane, right click on the top level 'blink' project and select Build Project

• Use Ctrl+B from the keyboard

When starting a project build, the Progress Window will appear, and information will scroll by in the Console Window.

 

2.3 Download and debug application code

2.3.1 Create a debug launch configuration

Eclipse do not come with a pre-defined debug configuration. To be able to download and debug an application, a Debug Configuration must be created.

1. From the main menu, select Run -> Debug Configurations...

2. Right-click GDB Hardware Debugging

3. Click New

Do the following changes in the Main tab:

4. Click the Select other... link on the bottom where it says Using GDB (DSF) Hardware Debugging Launcher

5. Select Standard GDB Hardware Debugging Launcher

6. Apply changes by clicking the OK button. Figure 2.9. Debug configuration - Main tab

Now proceed to the Debugger tab.

7. Change GDB Command to arm-none-eabi-gdb

8. Check Use remote target

9. Set JTAG Device to Generic TCP/IP

10. Set Port number to 2331

Figure 2.10. Debug configuration - Debugger tab

Proceed to the Startup tab.

11. Uncheck Reset and Delay

12. Uncheck Halt

13. In the textbox Initialization Commands enter:

set tdesc filename target-m3.xml

mon speed 4000 mon endian little mon flash download = 1 mon flash device = EFM32TG840F32

mon reset 0

Ensure that the device matches your target device.

14. If you are using a newer version of the J-Link GDB Server, omit the first line above

15. Check the Set breakpoint at box

16. Enter main in the corresponding textbox

17. Check the Resume box

18. The target-m3.xml file is included in the zip-file that comes with this application note. It should be extracted to the root Eclipse folder.

The "set desc" command applies a patch that corrects the CPU register view. This has been fixed in newer version of J-Link GDB Server. The "mon" command passes commands on to the hardware debugger itself. Please refer to SEGGER's UM08001 J-Link/J-Trace User Guide for an explanation of the initialization commands.

Figure 2.11. Debug configuration - Startup tab

Next, go to the Common tab

19. Check the Debug checkbox in the "Display in favorites menu" field.

20. Save your changes by clicking Apply and Close

Figure 2.12. Debug configuration - Common tab

Before starting a debug session, the J-Link GDB Server must be running in the background. On the Windows Start Menu, navigate to the SEGGER J-Link ARM folder and start J-Link GDB Server via SWD and connect to your target.

Now you can flash your microcontroller and start debugging your code directly by clicking the Debug icon on the main toolbar and select blink in the dropdown menu.

After debugging has started, verify that the connection between Eclipse through the J-Link GDB Server to your target hardware is OK. Switch focus to the running J-Link GDB Server

Figure 2.13. J-Link GDB Server in a debugging session

 

2.3.2 Embedded Systems Register View

The register viewer is a practical tool when you are debugging code for the peripherals of the microcontroller. Embedded Systems Register View (EmbSys) also contains documentation on the peripheral registers and their bitfields (as tooltips). To show the proper peripheral registers, EmbSys must be configured for the target device. To do this, follow these steps:

1. From main menu, select Window -> Preferences

2. In the Preferences menu, expand C/C++ -> Debug -> EmbSys Register View

3. Select Architecture: cortex-m3

4. Select Vendor: EnergyMicro

5. Select Device: EFM32TG840F32

6. Select OK to save your changes and return

Figure 2.14. EmbSys register viewer device selection

7. Navigate to C/C++ -> Debug -> EmbSys Register View -> Behavior

8. Set "Number of elements shown in the dropdown List" to the maximal amount.

9. Save the changes by clicking OK

To show EmbSys, change to debug perspective. From main menu select

10. Window -> Show view... -> Other...

11. Navigate to Debug

12. Select EmbSys Registers

13. Confirm with OK

Figure 2.15. EmbSys register viewer in action

Double click on a register to start viewing its content. Registers which you have selected get a green font. Changes in register contents are shown with red values. When hovering over a register's description column you see documentation for that register. To change a register, click on a cell in the Hex column, or the Bin column.

 

2.3.3 Run, Stop, Single-Step, Breakpoints

Look for the buttons shown in the figure below in the debug tab.

Figure 2.16. Debug button

These are all you need to do simple debugging. Breakpoints are set by doubleclicking in the left gutter in the source code tab. Set a breakpoint on the Delay(100) function call in the end of main() in blink.c, hit F8 several times and observe how the LED's on the STK/DK blink. (Hint: You must Terminate before reflashing and starting a new debug session. Exit and restart the GDB server if you get stuck).

Figure 2.17. Debug with breakpoint

 

2.3.4 Using the Memory viewer

Eclipse's memory monitor view is a default part of the debug view. The figure below shows two active memory monitors, one at address 0x20000200 and one at current stackpointer address. The view uses the Split Pane functionality, which in this case give you one hexadecimal rendering, and one ASCII rendering. New monitors are added by clicking the green plus sign as indicated.

Figure 2.18. Eclipse Memory Monitor

 

2.4 Tweaking Eclipse

2.4.1 Disabling parts of the Code Analysis feature

Code Analysis is a feature of Eclipse that tries to spot errors in your code while you are writing it, but it sometimes gets in your way, and is not always so good at finding definitions hidden in other files.

You can disable some or all of the Code Analysis warnings in Window -> Preferences, under C/C++ > Code Analysis.

 

2.4.2 Telling Eclipse about the external libraries

To take advantage of more of Eclipse's advanced IDE-features you can add the external libraries as linked folders in your project. Do this by right-clicking the project name, and selecting New -> Folder. Under Advanced >>, select Link to alternate location and browse to the library you want to link to.

Add bsp and drivers from the directory corresponding to your kit. Also add the emlib folder and the folder corresponding to your device under Device/EnergyMicro. Lastly, add a link to the install location of Sourcery CodeBench, and Eclipse will now be able help you look up function definitions etc.

When you have done this, Eclipse will show you function definitions when hovering over function calls, and by right-clicking you can jump to the file where the function is defined.

Figure 2.19. Hovering a function call gives you the beginning of its definition

 

3 Eclipse summary

This has just been an introduction to the basic steps of installing, configuring and using Eclipse as a code development environment for writing programs for EFM32 microcontrollers. Keep in mind that Eclipse is an advanced tool with hundreds of configuration options. The reader is encouraged to experiment further to finetune Eclipse. Use a search engine on the internet and you will find lots of articles, tutorials and books on using Eclipse.

Oscillator Design Considerations

This application note provides an introduction to the oscillators in EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko devices and provides guidelines in selecting correct components for their oscillator circuits.
The EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko devices contain two crystal oscillators: one low speed (32.768 kHz) and one high speed (4-32 MHz, 4-48 MHz, or 38-40 MHz). Topics covered include oscillator theory and some recommended crystals for these devices.
For simplicity, EFM32 is used throughout this document to represent the existing EFM32 Wonder Gecko, Gecko, Giant Gecko, Leopard Gecko, Tiny Gecko, Zero Gecko, or Happy Gecko MCU series, Wireless Gecko is used to represent the EFR32 Wireless Gecko portfolio devices, and EFM32 Gemstones is used to represent the next-generation Gecko MCUs (Pearl Gecko, Jade Gecko, and future devices).

 

1. Oscillator Theory

1.1 What is an Oscillator?

An oscillator is an electronic circuit which generates a repetitive time-varying signal, which in this context is used to clock communication and the execution of instructions in the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko microcontroller. Several ways of generating such a signal exists, all with different properties that influences cost, size and stability of the clock signal.
 

RC oscillators

RC oscillators are built from resistors, capacitors and an inverting amplifier. They come at a low cost and have a shorter startup time than the crystal oscillator, but variations in component values over temperature makes it difficult to precisely determine the oscillation frequency. The EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko devices provide two internal RC-oscillators, one high frequency RC oscillator (HFRCO) and one low frequency RC oscillator (LFRCO). In addition, an auxiliary 14 MHz RC oscillator (AUXHFRCO) is used for flash programming and debug trace. While the internal RC-oscillators will ensure proper operation of the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko device, some applications require higher accuracy than these can provide.

Crystal oscillators

Crystal oscillators use the mechanical vibration of a crystal to generate the clock signal. Due to the molecular composition of the crystal matter and the angle of which the crystal is cut, this type of oscillator is very precise and stable over a wide temperature range. The most commonly used crystal is the quartz crystal. Producing quartz crystals require very stable temperature and pressure conditions over a few weeks. This makes crystal oscillators more expensive than RC oscillators.

Ceramic resonators

Ceramic resonators operate in the same way as crystal oscillators. They are easier to manufacture and therefore cheaper than quartz crystals, but suffer from inferior precision in the oscillation frequency. As will be seen in subsequent chapters, the quality factor for ceramic resonators are lower than for crystal oscillators, which usually results in a faster startup time. This can be more important than precision in frequency for some applications.
This application note will focus on quartz crystals; however, the theory presented is also valid for ceramic resonators.
 

1.1.1 Piezoelectricity

Quartz crystals and ceramic resonators hold the direct piezoelectric property. This means an applied electric field will cause the crystal to deform. Conversely, a deformation of the crystal will cause a voltage across the terminals. Once the oscillator has started, the changing voltage on the terminals of the vibrating crystal is used as the clock signal.
 

1.2 Basic Principle of Oscillators

Figure 1.1. Feedback Oscillator Loop

The principle behind the oscillator is a positive feedback loop satisfying the Barkhausen condition: If the closed-loop gain is larger than unity and the total phase lag is 360°, the resulting closed-loop system is unstable and will self-reinforce. This is a necessary, but not sufficient, condition for oscillations to be present. When the necessary conditions are met, any disturbance (noise) in the oscillator will cause oscillations to start. The frequency that fulfills the Barkhausen condition is amplified the most, because it is in phase with the original signal.
The initial oscillations are very weak and it takes time to amplify the signal to the desired magnitude. When oscillations are established, only a small amount of energy is needed to compensate for losses in the circuit. Mathematically, a closed-loop gain of one is required to maintain steady state oscillations. The EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko relies on an internal regulator to adjust the closed-loop gain to unity when the clock signal reaches the desired amplitude.
Figure 1.1 Feedback Oscillator Loop on page 2 shows that the oscillator circuitry consists of two parts; an amplification stage and a filter that decides which frequency experience a 360° phase lag. In the case of a crystal oscillator, the filter consists of the crystal and external load capacitors.
 

1.2.1 Startup time

The magnitude of the closed-loop gain has great influence on the startup time. With high gain, the number of times the signal has to be propagated around the loop to reach the desired amplitude is reduced. For fast startup, a high gain is preferred.
For the same reason, the oscillation frequency influences the startup time. A crystal in the kHz range would have a considerably longer startup time than a crystal in the MHz range because the time it takes to circulate the loop is longer. Typical startup times for the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko is 200-400 ms for low frequencies and 200 µs to 400 µs in the high frequency domain.
 

1.3 Modeling the Crystal

The crystal can be described by the electrical equivalent circuit in the figure below.

Figure 1.2. The Electric Equivalent Circuit of a Crystal

• C_S is the motional capacitance. It represents the piezoelectric charge gained from a displacement in the crystal.
• R_S is the motional resistance. It represents the mechanical losses in the crystal.
• L_S is the motional inductance. It represents the moving mass in the crystal.
• C₀ is the shunt capacitance between the electrodes and stray capacitance from the casing.
For low frequencies, the electrical equivalent circuit will exhibit capacitive behavior as depicted in the following figure. The presence of the inductor becomes more noticeable as the frequency, and thus reactance, increases. Ignoring the shunt capacitance C₀, the series resonant frequency is defined where the reactance of the inductor and capacitor cancels. At this frequency the crystal appears only resistive with no shift in phase. The series resonance frequency therefore decides the values of C_S and L_S and can be calculated with the equation below. The series resonance frequency is the natural resonance frequency where the energy transformation between mechanical and electrical energy is most effective.

Figure 1.3. Reactance vs. Frequency
 
At higher frequencies, the equivalent circuit will appear inductive, which implies higher impedance. When the inductive reactance from the crystal cancels the capacitive reactance from shunt capacitance C₀, another resonance frequency with zero phase shift exists. This frequency is called the anti-resonant frequency, f_A. At this frequency, the impedance is at its maximum. The inductance in the crystal and the shunt capacitance will feed each other and the lowest possible current draw is obtained.

The range of frequencies between f_S and f_A is called the area of parallel resonance and is where the crystal normally will oscillate. At the resonant frequency, the phase lag in the feedback loop is provided by an amplifier with 180° phase lag and two capacitors with a combined 180° phase lag. In practice, the amplifier provides a little more than 180° phase shift, which means the crystal has to appear slightly inductive to fulfill the Barkhausen criterion.
 

1.3.1 Series and Parallel Resonant Crystals

Physically there are no difference between series and parallel resonant crystals. Series resonant crystals are specified to oscillate at the series resonant frequency where the crystal appears with no reactance. Because of this, no external capacitance should be present as this would lower the oscillating frequency to below the natural resonance frequency. These crystals are intended for use in circuits with no external capacitors where the oscillator circuit provides 360° phase shift.
Parallel resonant crystals requires an external capacitive load to oscillate at the specified frequency and this is the resonance mode required for the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko. The exact oscillation frequency for a parallel resonant crystal can be calculated with the equation below, where C_L is the external capacitance seen by the crystal. C_L is therefore an important design parameter and is given in the datasheet for parallel resonant crystals.

 

2. EFM32 Crystal Oscillators

The EFM32 devices include a variety of oscillators, including fully internal low speed and high speed RC oscillators (not covered by this application note). These enable full operation in all energy modes without any external oscillator components. If the application requires a more accurate clock, the EFM32 includes two crystal oscillators, the Low Frequency Crystal Oscillator (LFXO) and the High Frequency Crystal Oscillator (HFXO). These oscillators require an external clock or crystal and load capacitors connected to the crystal oscillator pins of the EFM32. The LFXO supports crystals with a nominal frequency of 32.768 kHz, while the HFXO supports frequencies from 4 to 32 MHz ( Up to 48 MHz in parts that support this frequency for the system clock). External oscillators which provide sine and square waves are also supported, see AN0002 Hardware Design Considerations for register settings and pin connections. Both the high and low frequency clock sources can be used simultaneously.
In the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko the oscillator circuits are designed as a Pierce oscillator as shown in Figure 2.1 The Pierce Oscillator in the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko on page 5.

Figure 2.1. The Pierce Oscillator in the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko
The Pierce oscillator is known to be stable for a wide range of frequencies and for its low power consumption.
The EFM32 crystal oscillators use a relatively low oscillation amplitude, which can lead to a lower oscillation frequency than stated as the nominal value in the crystals datasheet. More information on this effect is given in 3.4 Frequency Pulling.
 

2.1 Timeout and Glitch Detection

To ensure that the XO clock signals are not used internally in the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko before they are stable, both the HFXO and the LFXO include a configurable timeout (configured in LFXOTIMOUT and HFXOTIMEOUT in CMU_CTRL). When the XO starts up the timeout counter will count to the configured number of cycles before the clock signal propagates to the internal clock trees and the digital logic. For the HFXO there is also a glitch detector that can be enabled (HFXOGLITCHDETEN in CMU_CTRL). With this set, any glitches detected during the timeout period will result in the timeout counter starting over again. The clock will then not propagate until it has run a full timeout period without glitches. After the timeout period has passed successfully the glitch detector is turned off automatically to save power.
 

2.2 Oscillator Configuration in Configurator

The [Configurator] in Simplicity Studio contains a tool to help users configure both load capacitance and software settings for using the LFXO and the HFXO. Once the correct HW configuration has been found the Designer can output C-code which should be run in the application. It is important that the SW settings from [Configurator] are used to ensure reliable operation of the oscillator.
 

2.3 External Clock and Buffered Sine Input

The HFXO and LFXO oscillators can be used as inputs for an externally generated digital clock signal. When using the oscillators in this way, connect the clock input to HFXTAL_N or LFXTAL_N and configuring . The max frequency of these inputs are limited by the max clock frequency of the device (see the device data sheet for more information). An externally buffered sine signal can also be applied to the HFXTAL_N or LFXTAL_N pin. The amplitude of this signal must be at least 200 mV peak-to-peak, and the frequency must be the same as required when using crystals with the HFXO and LFXO. The oscillation mode for the LFXO and HFXO is configured in HFXOMODE/LFXOMODE in CMU_CTRL.
 

3. Crystal Parameters

3.1 Quality Factor

The quality factor Q is a measure of the efficiency or the relative storage of energy to dissipation of energy in the crystal. For the electrical-equivalent circuit, the equation below states the relation between R, C and Q. In practice, crystals with higher Q-values are more accurate, but have a smaller bandwidth for which they oscillate. Therefore, high Q-factor crystals will normally start slower than crystals with higher frequency tolerance. Typically, crystals have higher Q-factor than ceramic resonators. Crystals would therefore be expected to have a longer startup time than ceramic resonators.

X_LS and X_CS are the reactance of L_S and C_S, respectively, at the operating frequency of the crystal.
 

3.2 Load Capacitance

As seen in the equation below, the two capacitors C_L1 and C_L2 are the loads of the crystal. The effective load capacitance, C_L, as seen from the XTAL_N and XTAL_P pins on the EFM32 or EZR32 is the series combination of C_L1 and C_L2 through ground.

Where C_stray is the pin capacitance of the microcontroller and any parasitic capacitance, and can often be assumed in the range 2-5 pF. Right choice of C_L is important for proper operating frequency. Crystals with small load capacitance would typically start faster than crystals requiring a large C_L. Large load capacitors also increase power consumption. It is recommended to use a crystal with C_L as specified in 6. Recommended Crystals. The EFM32 or EZR32 device datasheets also contain more information on the allowed load capacitance range.
Note that EFM32 Gemstones or Wireless Gecko devices have internal loading capacitors and do not need external capacitors connected to the crystal. See the device data sheet or reference manual for more information.
 

3.3 Equivalent Series Resistance

The Equivalent Series Resistance is the resistance in the crystal during oscillation and varies with the resonance frequency. ESR, given by the equation below, will typically decrease with increasing oscillation frequency.

The HFXO/LFXO circuits of the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko cannot guarantee startup of crystals with ESR larger than a certain limit. Please refer to the device datasheet for further details. The smaller the ESR, compared to this maximum value, the better gain margin for startup of the crystal which in turn reduces the startup time. Additionally, a small ESR value gives lower power consumption during oscillation.
Note that HF crystals have ESR of a few tens of Ohms as compared to the LF crystals which have ESR values normally measured in kOhm. Therefore a few Ohm of series resistance has more influence on the startup margin in the MHz range as compared to the kHz range.
 

3.4 Frequency Pulling

As the crystal oscillators in the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko use a relatively low oscillation amplitude, the oscillation frequency can be lower than stated in the datasheet when using the suggested load capacitance. This offset is best found by measuring the resulting frequency when using the suggested load capacitance. The offset will be stable and not affected by temperature, voltage or aging. If it is desirable to achieve the nominal frequency given for the crystal, there are two options:
• Option A — Order a crystal from the crystal vendor that has a nominal frequency equal to the frequency you want to achieve plus the measured offset frequency.
• Option B — It is possible to slightly alter the oscillation frequency of a crystal by adjusting the load capacitance (C_L1 and C_L2). The pullability of the oscillation system refers to which extent it is possible to tune the resonance frequency of the crystal by changing these values. The crystal sees these capacitors in series through ground, parallel to the closed loop. They will therefore slightly alter the anti-resonance frequency of the crystal. The equation below shows the pullability in terms of frequency change in ppm per change in combined load capacitance in pF.

 

3.5 Drive Level

Drive level is a measure of the power dissipated in the crystal. The crystal manufacturer states the maximum value tolerated by the crystal. Exceeding this value can damage the crystal.
DL = ESR × I ²
I is the RMS current flowing through the crystal. An external resistor can be added to limit the drive level if necessary; however this is not recommended unless DL is too high since it reduces the gain margin and increases power consumption of the oscillator.
 

3.6 Minimum Negative Resistance

A critical condition for oscillations to build up requires the energy supplied to exceed the energy dissipated in the circuit. In other words, the negative resistance of the amplifier has to exceed the equivalent series resistance in the crystal. An approximate formula for negative resistance is given in the equation below.

Where g_m is the transconductance of the oscillator circuitry. To ensure safe operation over all voltage and temperature variations, the lowest allowed R_neg is given by the equation below.
-Rneg  >  2 × ESRmax
If the negative resistance is not high enough to satisfy this criterion, another crystal with lower ESR and/or load capacity requirements should be chosen. The XO Configurator in [Configurator] in Simplicity Studio is able to calculate the R_neg value for your design based on the load and shunt capacitance, internal loss and frequency. The equation above shows an approximate formula for this calculation which excludes shunt capacitance and internal loss.
 

3.7 Frequency Stability

Frequency stability is the maximum frequency deviation from the specified oscillating frequency over the given operating temperature range.
 

3.8 Frequency Tolerance

Frequency tolerance is the maximum frequency deviation from the specified oscillating frequency at 25 °C. This parameter gives an indication of variations between individual crystals.
 

3.9 PCB Layout

To minimize noise sensitivity caused by parasitic antenna and spurious coupling phenomena, the distance between the crystal, capacitors (when needed), and the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko oscillator pins should be as short as possible. If it is not possible to place the external oscillator components close to the oscillator pins, care should be taken when routing these signals. Avoid long traces underneath the EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko package and other circuitry that could create spurious coupling with logic activity. Also avoid routing any other signals through the crystal area.
The ground side of the two capacitors must be connected to ground. These connections should be as short as possible and of equal length for each of the capacitors. Ensure that the ground plane underneath the oscillator is of good quality. Do not use a separate ground plane under the oscillator with a narrow connection to the reference ground as this can act as an antenna. To avoid coupling from surrounding signal traces, it is a good practice to place a grounded guard ring around the oscillator and its components.
 

3.10 Software Configuration

The EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko allows for run-time configuration of the transconductance (g_m) of the HFXO and the LFXO during oscillation build-up. The following bit fields are used:
HFXO
HFXOBOOST[1:0] in CMU_CTRL
LFXO
• LFXOBOOST in CMU_CTRL
• REDLFXOBOOST in EMU_AUXCTRL (not available in all devices)
The recommended settings for these bits depend on the load and shunt capacitances of the oscillator design. The LFXO/HFXO configurator in the [Configurator] in Simplicity Studio creates C-code that sets these configuration bits correctly according to the frequency, maximum ESR, shunt and load capacitance of the crystal. It is important that these recommendations are followed as incorrect settings can lead to unreliable operation of the crystal oscillator.
 

4. Reducing Power Consumption

The power consumption of the crystal oscillator is mostly determined by the drive level of the oscillator. This equals the power dissipated in the crystal as given in the equation below.

V_pp is the peak to peak voltage across the crystal at the resonance frequency.
Because the internal buffer draws some current regardless of clock frequency, the average power consumption per MHz is usually lower for high clock frequencies. In the energy conscious sense it is therefore favorable to alternate between short periods in run mode with HFXO enabled and lower energy modes where HFXO is not running. Since the startup time depends on clock frequency, high frequency crystals are recommended to reduce the startup time.
During startup the current consumption is higher than after oscillations has stabilized. A short startup time reduces the period of which the current consumption of the oscillator is high and is therefore essential if the oscillator is frequently switched on and off. In general one would like the circuit to be operational as fast as possible and a fast startup time is therefore favorable. Crystals with low ESR and load capacitance typically have the shortest startup time and consumes the least amount of power.
Energy consumption can be reduced by choosing a HFXO crystal in the lower frequency range in applications where entering a deeper sleep mode is not feasible.

 

5. Considerations for Radio Applications with the EFR32 Wireless Gecko Portfolio

5.1 General Notes

The crystal oscillator of the EFR32 Wireless Gecko portfolio is very similar to those used in EFM32. All of the recommendations discussed previously can applied also for this device. This section adds a few details about specific requirements related to wireless applications.
While EFR32 devices support a range of 38 to 40 MHz, the recommended value is 38.4 MHz. Transceiver electrical specifications are based on this frequency, and Silicon Labs protocol stacks use this as the default.
Different applications have varying temperature and frequency tolerance requirements. These are considered together as they are interdependent.
The crystal frequency tolerance is determined by various aspects of the design:
Required frequency tolerance of the protocol
For example 802.15.4 applications require +/- 40 ppm accuracy under all conditions.
Temperature range
The S-shaped temperature characteristic of AT-cut crystals becomes steeply negative at low temperatures, steeply positive at high temperatures. A larger temperature range requires a specific cut angle of the crystal to bound the absolute accuracy. Most crystals are specified from -40 °C to +85 °C, but some applications may require operation up to 105 °C or 125 °C ambient temperature.
Manufacturing accuracy
Individual crystals have a frequency error at 25 °C. This is typically specified as ±10 ppm "manufacturing tolerance" or "make tolerance". This error adds to the temperature error.
Aging tolerance
Crystals drift over time, typically 1-2 ppm per year. Excessive heat during assembly or from hand soldering may also prematurely age a crystal.
The allowable frequency error of the crystal is the sum of temperature, board-to-board, and crystal-to-crystal variations.
 

5.2 Crystal Loading and Production Tuning

The load capacitance, C_L, is implemented on-chip by two tunable capacitors. External capacitors are neither required nor recommended.
The load capacitor tuning range in pF is given in the datasheet by CHFXO_T with a resolution of SSHFXO per step. Adding an allowance for fixed PCB parasitic capacitance this will accommodate a crystal load capacitance range of approximately 6 to 12 pF. Resulting frequency per step depends on the crystal's pulling sensitivity.
 

5.2.1 Tuning Strategies

The on-chip variable load capacitor may be used in one of two ways.
• A fixed value may be used for all units. During design a number of units should be characterized and an average center CTUNE value determined. Some crystal vendors may provide characterized samples to help tune to the center of the crystal distribution. In corner cases the remaining error should be in the order of a few ppm only, depending on manufacturing spread (PCB parasitics, component variation, etc.).
• Each unit may also be calibrated in production. A unique value of CTUNE is determined per unit and stored in flash memory. This calibrates out the manufacturing error of the crystal, leaving only the temperature error and aging components. This may allow the system to operate across a broader temperature range or with a less accurate crystal at the expense of production calibration time. The variable on-chip loading capacitor can theoretically be used to offset temperature-induced errors as well. While simple in concept this is difficult in practice primarily due to temperature characteristic differences from crystal to crystal.
Crystal ppm error is measured using the RF transmitter operating in CW transmit mode.
 

5.3 PCB Layout

The crystal section PCB layout should be kept compact and close to the IC. Longer traces increase possibility of spurious transmission and increase the fixed parasitic loading capacitance. The crystal's case ground pins should be grounded. Please refer to AN928: "EFR32 Layout Design Guide" for further notes on this subject. Application notes can be found on the Silicon Labs website (www.silabs.com) or in Simplicity Studio using the [Application Notes] tile.

5.4 External Tuning Capacitance

All required crystal loading capacitance is on-chip, therefore, external loading capacitors are not recommended.
 

5.5 External Oscillator Operation

For narrowband applications the system reference frequency may be provided by an external oscillator such as a Temperature Compensated Crystal Oscillator (TCXO). The TCXO output is connected to the HFXTAL_N pin and the MODE bit set in the CMU_HFXOCTRL register. Refer to the data sheet Electrical Specifications for amplitude, frequency, and waveform requirements.
 
 

6. Recommended Crystals

6.1 General Notes for Crystal Selection

When deciding upon which crystal to employ, the following considerations could be helpful to ensure a proper functioning oscillator.

Precision
High quality crystals are very precise, but come at a higher cost. Ceramic resonators are cheaper, but less precise. However, if no special precision is needed, the internal RC oscillators consume less power at the same frequency. Consult the device datasheet for details.
Operating environment
Temperature, humidity and mechanical vibration affects the stability properties. For crystals, define what crystal cut is more appropriate. For most applications, AT cut is an excellent choice due to good temperature stability over a wide temperature range. SC cut has good stability when exposed to mechanical vibrations, but suffers from humidity and temperature changes. Many more cuts with different properties exists.

Package
Surface mount or through-hole. If size is critical, define maximum package dimensions.

Find load capacitors

If C_{L1, L2} is within range specified by the crystal datasheet, check if it meets a standard capacitor value. If not, use the nearest value available. A variable capacitor can be used to pull the correct frequency if desired.

Calculate negative resistance

If the magnitude of the negative resistance is less than 2xESR_max, then find another crystal or adjust the load capacitance.

The recommended crystals are chosen from a selection of popular crystals with different ESR, cost, frequency stability and tolerance. By examining the list of considerations above, one should be able to find a suitable crystal.
All the recommended crystals are fundamental mode, as is recommended for EFM32, EZR32, EFM32 Gemstones, or Wireless Gecko.