Question

Is it possible to implement conditional compiling in my source code so that it works for specific families?

Answer

Yes, our source code implements a series of define macros that can be leveraged to achieve this functionality. This technique is already used across multiple EMLIB modules to provide compatibility with multiple target devices. It can be useful in cases where a single source code file is to be used with multiple targets, but different functionalities are required.

It’s important to note that when building an MCU project with the Simplicity Studio IDE, the desired target architecture needs to be selected so that the relevant header files for the device are included in the project. The use of conditional compiling macros doesn’t override this functionality and it’s simply to allow a single source code file to be used across projects with different target architectures.

The necessary macros are found inside the header file containing the header file of the specific device usually located in the following path:

• <STUDIO_SDK_LOCATION>\platform\Device\SilionLabs<Desired device family>\Include
• e.g: \platform\Device\SiliconLabs\EFM32GG11B\Include\efm32gg11b820f2048gl192.h

Look for the “Part Family” define group. The relevant macros are highlighted in yellow in Figure 1 below:

Inside your source code, you need to implement a structure such as the following to determine a code snipped that will be conditionally compiled:

#if (defined(_EFM32_GIANT_FAMILY) && defined(_SILICON_LABS_32B_SERIES_1_CONFIG_1))
/* Conditionally compiled user code */
#endif

The same structure applies for Series 2 devices, only the “config” macro needs to be updated to the series 2 version. As for Series 0 devices, the “config” macro is not available, therefore, the “_SILICON_LABS_32B_SERIES_0” macro should be implemented instead. For example, for the Giant Gecko Series 0 family see the snippet below:

#if (defined(_EFM32_GIANT_FAMILY) && defined(_SILICON_LABS_32B_SERIES_0))
/* Conditionally compiled user code */
#endif

Attached to this KBA you can find a simple source code file that works with the SLSTK3700 and STK3701A development kits (Giant Gecko series 0 and 1 respectively). It’s a modified version of the “Blink” example and it integrates the macros to conditionally compile a different delay value for each board and to enable the DCDC converter in the STK3701A.

At a high level, the EFR32 series 1 chip has two major blocks: MCU + Radio.

By default, most of the applications use EFR32 series 1 chip for both its MCU and radio functionality, but there are certain applications where the designer might want to use the EFR32 chip as an MCU only device i.e. without radio functionality. A reason for such usage would be due to some features that other MCUs might not have or to simply keep the application future proof with the possibility of wireless capability.

In the case where the radio is not used, special care needs to be taken to connect and configure the part properly. 
The table below provides a comparison of generic pin connections for the standard EFR32 with radio used versus the non-radio use case:

* Please note that even if the Radio block of the EFR32 chip is not used, DC voltage should be supplied at the appropriate power supply (PAVDD, RFVDD) pins along with the respective filtering components. A detailed pin connection and filtering component information are given in AN0002.1.

REMINDER:
The EFR32 Series 1 Supply constraints are as follows:-

• AVDD must be the highest voltage in the system
• VREGVDD must be connected to AVDD on DCDC-enabled devices
• AVDD >= DVDD
• AVDD >= PAVDD ( For 2.4GHz or Dual-band devices, PAVDD refers to the device pin. For sub-GHz devices, PAVDD refers to the external power amplifier supply)
• AVDD >= RFVDD
• AVDD >= IOVDD
• DVDD >= DECOUPLE

The purpose of this knowledge base article is to demonstrate the usage of the Giant Gecko GG11 started kit to implement a sound-based guitar and ukulele tuner. A small background on instrument tuners is provided followed by a brief description of the hardware used from the development board and its implementation through functional blocks. Lastly, the general description of the software workflow is discussed. The article includes the simplicity studio project (.sls), please refer to it and it’s readme file for details on the software implementation and how to run the application. The following KBA contains a series of steps on how to import .sls files into Simplicity Studio.

1. Introduction

An electric tuner aims to measure the frequency of a note played by an instrument, this is then correlated to its associated musical note in a scale, and feedback is provided to the user of the “closeness” of the played note to the desired one, usually in a visual way.

Tuners may record the input note by different means, usually through direct connection by an input jack, by sound (using a microphone) or by vibration (using a piezoelectric sensor).

Lastly, a tuner may be classified as standard or chromatic, the former allows to tune an instrument to its standard notes and the later will display the tuning at any pitch on a 12-notes chromatic scale. This project follows a sound approach with standard tuning for guitar and ukulele.

2. Hardware implementation

This example is implemented in the SLSTK3701A starter kit for the EFM32GG11 MCU. Multiple on-board hardware elements are leveraged such as the MEMS microphones, push-buttons, and LCD screen; MCU peripherals such as the PRS, GPIO interrupts, USART (I2S mode), CMU and LDMA. Core-specific peripherals like the DSP, FPU, and NVIC are also utilized.

Figure 1 below shows a high-level functional block representation of the project, each block is marked by a green background.

3. Functional blocks

3.1 Input detection

The tuner interacts with 3 different inputs: one audio and two mechanical. The audio input is captured by the 2 MEMS microphones in the SLSTK and the mechanical ones by the two available push-buttons.

3.1.1 Audio Input

The on-board microphones generate a PDM (Pulse Density Modulation) signal as its output, given that the MCU has no specialized peripheral for this, an IC transducer/codec is implemented. The codec is routed to the USART 3 peripheral of the MCU that can be configured to operate in I2S mode. This implementation is observed in Figure 2 below.

According to the microphone’s datasheet, the microphone operates in 3 different states based on the VDD value and the frequency of the input clock. A high value in VDD and a frequency >= 1 Mhz will take the device to an active mode whereas a frequency < 1Khz will take it to a sleep mode.

The clock signal for the microphones (PDM_CLK) is generated by the codec which requires 2 clock inputs the “bit clock” (BCLK) and the “word select” or “left-right clock” (LRCLK).

• “Bit clock”: Pulses once for each data bit in the data line, relative to the baud rate of  the I2S peripheral

• “Left-right clock”: Determines the sampling rate, and the channel that data comes from, generated by the CS (Chip select) of the peripheral
  • High: Right channel
  • Low: Left channel

According to the datasheet of the codec, BCLK should be at least 64x the LRCLK rate and the generated PDM_CLK will be 64x the LRCLK rate. Furthermore, it’s stated that the minimum sampling rate should be between 4 - 96 kHz leading to a PDM_CLK ranging from 256 kHz to 6.144 MHz.

Since the PDM_CLK should be at least 1 MHz, the LRCLK should be PDM_CLK/64 or 15.625 KHz. Still, during testing, it was determined that pushing the LRCLK rate as low as 2 kHz still rendered reliable results this is important for the resolution of the application as explained in the Frequency acquisition section.

Following the selected sampling rate as 2 kHz, word size of 32-bits, and 2 channels, the Bit clock or baud rate is determined to be 2000 x 32 x 2 or 128000 bits/s.

It’s important to note that the data from both channels (left and right) is transferred through the same data line, and the application should keep track of the source in the RX buffer, this is described in the Data transfer section.

3.1.2 Mechanical inputs

The SLSTK has 2 push-buttons available for user interaction. Push-button 0 is used to initialize the tuner whereas push-button 1 is used to switch between target instrument (Guitar & Ukulele) once the tuner is operating. Each input is managed in different ways, button 0 is routed to the PRS (Peripheral Reflex System) peripheral, and button 1 is managed through the edge interrupt of the GPIO peripheral.

The PRS system allows routing an event in a peripheral (producer) towards another peripheral (consumer), in this case, the GPIO level change towards the USART peripheral enabling its RX and TX components. This is done without the CPU intervention allowing the system to stay in a low energy mode. Further details on the PRS and GPIO peripherals can be found in sections 15 and 34 of the EFM32GG11 reference manual.

3.2 Data transfer

Following the idea of low energy mode, the LDMA (Linked Direct Memory Access) peripheral is enabled to transfer the microphone data in the RX buffer of the USART to RAM without the need for the CPU. Upon a transfer request the LDMA uses the descriptor data in memory to perform its operations, an extra property is that descriptor may link to new ones with different properties allowing for different operations on each transfer or looped process, which is the case of this example.

The LDMA peripheral is configured to trigger peripheral to memory transfers based on the RXDATAV and RXDATAVRIGHT USART status flags, the former indicates that data is available in the buffer and the second that data from the right channel is available allowing to differentiate between channels. The DMASPLIT in the USART_I2SCTRL register should be enabled to allow channel differentiation.

For this application only the data from the left microphone is used, still, the transfers for both channels are implemented for scalability. The left channel transfer has two linked descriptors assigned each with its own target buffer and the following main properties:

• 1 byte-sized transfers
• Total transfers (in bytes) = 4 x buffer size (uint32_t buffers)
• Interrupt generated on descriptor completion (full buffer)
• Looped linkage between descriptors

The right channel transfer descriptor performs a single byte transfer to a dummy buffer with no interrupts generated.

3.3 Processing

Once data from the microphone has been captured and the CPU informed, the processing begins which can be divided into three main steps: raw data processing, frequency acquisition, and tuning algorithm.

3.3.1 Raw data processing

This segment manages and adjusts the microphone data before it’s processed for frequency extraction.

• Determine the data buffer to process
  • There’re 2 buffers available for the left channel in the application
• Match the endianness of the data and adjust the number of bits
  • Incoming data is big-endian whereas the MCU is little-endian. Only 20 bits of data are >relevant according to the codec datasheet

3.3.2 Frequency acquisition

This segment determines the main frequency component of the input signal leveraging the CMSIS-DSP library that provides a series of functions for signal processing.

• Apply a Hanning window to the data
  • Non-integer periods of data generate undesired high-frequency components after FFT processing, more details can be found in the following link
  • Hanning window coefficients are generated in code (arm_cos_f32)

• Perform an FFT on the data (arm_rfft_fast_f32)
  • The resolution of the FFT will be dependent on the sampling frequency and the number of FFT elements. Also, the frequency bin range is half of the sampling frequency

• Get the magnitude of the real and imaginary pairs from the FFT (arm_cmplx_mag_f32)
• Determine the bin with the highest magnitude (arm_max_f32)
• Verify if a second harmonic was detected
  • Magnitude comparison of the highest bin and that at half of the frequency
• Determine the frequency of the input

3.4 Tuning algorithm

This is a simple heuristic algorithm that compares the detected frequency with a series of frequency brackets surrounding a target fundamental frequency. The targets are dependent on the selected instrument and correspond to the frequencies of each string when tuned, these values are hardcoded and adjusted to the nearest integer that can be detected based on the resolution of the FFT. For the example code, this resolution is 3.91 Hz per frequency bin. Figure 3 below shows a graphic representation of the frequency brackets.

Based on the bracket, the algorithm will determine the properties of the figures and text to be displayed on the LCD screen in the last functional block.

3.5 Feedback

The LCD screen management is leveraged through the GLIB (Graphics Library) As mentioned before, depending on the bracket that the detected frequency falls, a different set of properties are defined and used to display specific figures related to the “tuning level” detected. Figure 4 below shows an example of the 3 cases portrayed in Figure 3.

Please refer to the following KBA for and introductory documentation on using the GLIB library.

4. Software flow

The application begins by initializing the different MCU peripherals as well as the 3 flow control flags:

• “buffer_select” - Indicate the buffer to be processed
• “buffer_ready” - Indicate that a buffer is ready to be processed
• “instrument_toggle” – Indicate the instrument that is being tuned (guitar or ukulele)

An initial interface screen is displayed, and the processor goes to EM1 (Energy Mode 1). The data acquisition and processing begin until button 0 is pressed, from this point, the application will run continuously until the board is reset.

Once push-button 0 is pressed, a PRS signal enables the I2S RX and TX components allowing microphone data to be captured, this in terms begins the LDMA transfers and once a full transfer is complete (a buffer of data is ready) an interruption is generated toggling the “buffer_select” flag and making the system leave EM1. Pressing push-button 1 will also take the system out of EM1 although its real purpose is to control the “instrument_toggle” flag.

Once a buffer of data is ready, the filled buffer (out of the two available) is selected based on the “buffer_select” flag. Its contents are pre-processed and the frequency analysis is performed as described in the Processing section.

Once the frequency is known, based on the “instrument_toggle” flag, the adequate tuning algorithm is executed either guitar or ukulele. They both have the same heuristic nature each differing on the target frequencies. This algorithm will define a series of properties that are passed as a structure to the LCD updating routine.

After the LCD update, the “buffer_ready” flag is cleared indicating that a new buffer may be processed. It’s important to note that I2S data acquisition and LDMA transfers are still running in the background during the data processing cycle. Figure 5 below demonstrates the overall software operation in a graphical manner.

References

[1] https://www.silabs.com/community/software/simplicity-studio/knowledge-base.entry.html/2018/09/26/exporting_importing-IEqP

[2] https://www.silabs.com/documents/public/reference-manuals/efm32gg11-rm.pdf

[3] https://arm-software.github.io/CMSIS_5/DSP/html/index.html

[4] https://download.ni.com/evaluation/pxi/Understanding FFTs and Windowing.pdf

[5] https://docs.silabs.com/mcu/latest/efm32gg11/group-glib

[6] https://www.silabs.com/community/wireless/proprietary/knowledge-base.entry.html/2018/08/21/using_the_lcd_screen-UW7Q

Question

How do I use the alternate excite pin for LESENSE excitation in series 1 devices?

Answer

There are a total of 16 channels in the LESENSE peripheral, and there are 8 alternate excitation pins. Each alternate excite pin is mapped to Channel X and Channel X + 8 with 0 < X < 8. For pin mapping of each device, please refer to the Alternate Functionality Overview section in the device's datasheet.

In order to use the alternate excitation pin, add the following sequence into the LESENSE initialization routine:

1. Set ALTEX to true in the LESENSE_CHx_INTERACT register (x being the channel number you want to configure).

2. Set ALTEXMAP to ALTEX in the LESENSE_CTRL register.

3. Enable the corresponding channel pin (CHxPEN) and Altex pin (ALTEXxPEN) in LESENSE_ROUTEPEN register.

4. Configure the LESENSE_ALTCONFIG register for desired setting (check register description in the reference manual for more information).

5. Make sure the corresponding GPIO pin for alternate excite is set to push-pull output if the excitation type is logical low or logical high.

You should be able to see the excitation pulse in the alternate excite pins with these configuration added.

An example of using LESENSE excitation pin is attached in this article. The example runs on an EFR32MG12 starter kit and the excitation pulse is on PA8, which is the alternate excitation pin for LESENSE channel 0 on EFR32MG12. The code added to enable alternate excite is:

  LESENSE -> CTRL |= LESENSE_CTRL_ALTEXMAP_ALTEX;
  LESENSE -> ROUTEPEN |= LESENSE_ROUTEPEN_ALTEX0PEN | LESENSE_ROUTEPEN_CH0PEN;
  LESENSE -> CH[0].INTERACT |= LESENSE_CH_INTERACT_ALTEX;
  LESENSE -> ALTEXCONF |= LESENSE_ALTEXCONF_IDLECONF0_LOW;

Introduction

EFR32 devices allow the JTAG TDI/TDO pins to be used for other functions when not needed for JTAG debugging. Under certain circumstances, such as an unexpected reset during debug, control of these pins can unexpectedly be transferred to the debug peripheral. On Series 2 devices this happens more frequently due to changes in the reset topology. In such cases, the device must be reset again to regain normal control over the pins.

Background

JTAG and SWD

EFR32 supports debugging through either the JTAG or the SWD protocol. The JTAG protocol is an industrial standard for testing and verifying PCBs that utilizes 4 pins; TCK, TMS, TDI and TDO. SWD is an ARM proprietary protocol that is interoperable with a JTAG test environment, but utilizing only two pins, the TCK and TMS pins.

Debug Port

The Serial Wire/JTAG Debug Port (SWJ-DP) is responsible for implementing both the JTAG and the SWD interface. The SWJ-DP also facilitates for switching between the two protocols on demand.

The SWJ-DP allows a designer to allocate the JTAG TDI and TDO pins to other functionality, such as GPIO, when only using the SWD interface. 

On startup the SWJ-DP will, for compatibility reasons, default to JTAG mode. In order to switch to SWD mode, a debugger will have to transmit a specific initialization sequence on the TCK and TMS pins. This initialization sequence is designed such that it will not affect any JTAG devices on the same bus.

JTAG-on-demand

JTAG-on-demand is an EFR32-specific feature that allows an EFR32 device to appear as defaulting to SWD mode. This means that the TDI and TDO pins are allocated as normal GPIO at startup instead of being allocated to the debug interface.

JTAG-on-demand will reallocate the TDI and TDO pin to the debug interface when the SWJ-DP is in JTAG mode and detects JTAG traffic. Once JTAG-on-demand has been activated, it will not be deactivated until the next full reset of the chip (and debug interface).

JTAG-on-demand can be overridden by writing to the GPIO.DBGROUTEPEN register. Attempting to write the relevant bits while the debug circuitry is active will cause a BusFault on Series 2 devices.

Series 2 reset topology

EFR32 Series 2 devices have a different reset topology than EFR32 Series 1 devices. The most notable change is that in Series 2 devices the debug interface is reset on assertion of the RESETn pin.

Error Conditions

If anything except the full SWD initialization sequence is received by the EFR32 on the debug interface while the SWJ-DP is in JTAG-mode, JTAG-on-demand will activate and transfer control of the TDI and TDO pins to the SWJ-DP.

When control of the pins has been transferred, the pins cannot be used in any other function, including normal GPIO, SWO or ETM Trace.

There are two scenarios in which loss of control over TDI and TDO is likely to occur:

• If the EFR32 is reset in a way that causes the debug interface to be reset while there is an active SWD debug session. For Series 2 device, this includes reset via the RESETn pin. The debug adapter will be unable to detect this reset in all circumstances, causing the debug adapter to continue communicating over SWD, activating the JTAG-on-demand feature.
• If the debug adapter attempts to initialize the SWD connection before the EFR32 has fully exited reset so that the SWD initialization sequence is not registered. This causes JTAG-on-demand to activate when verifying the connection as required by ARM.

While it is possible for this to occur on EFR32 Series 1 devices, it is a lot easier to trigger on Series 2 devices due to the change in reset topology. It is also not possible to override the JTAG-on-demand feature on Series 2 devices, contrary to Series 1 devices where this is possible.

Consequences

When JTAG-on-demand is activated on an EFR32 Series 2 device, the following will happen

• SWO will stop working
• ETM Trace will stop working
• Loss of control over GPIO pins PA3/PA4

For Silicon Labs development kits, the following are features that can be affected depending on what is connected to PA3/PA4:

• VUART
• Simplicity Studio Code Correlation
• External SPI Flash
• VCOM Flow Control (CTS always high)
• Button stuck high

Workaround

Once the condition occurs, the only known workaround is to disconnect all active debug sessions, reset the target through the RESETn pin or toggling power.

Glossary

Question

How to print messages to Virtual COM port by using printf() function in an MCU application?

Answer

We provide so called RETARGET functions with the aim of avoiding the needs of the low level UART peripheral configuration. The following step-by-step guide shows how to add all the necessary files and functions to a project from the scratch.

1. Create an empty MCU project

File -> New -> Project...

Figure 1.
Create an empty MCU project.

2. Copy (or link) the following emlib and RETARGET files

emlib from "<StudioPath>\v4\developer\sdks\gecko_sdk_suite\v2.7\platform\emlib\src":

• em_cmu.c
• em_core.c
• em_gpio.c
• em_usart.c

RETARGET from "<StudioPath>\v4\developer\sdks\gecko_sdk_suite\v2.7\hardware\kit\common\drivers":

• retargetio.c
• retargetserial.c

Figure 2.
Files in the project.

Note: The header files are added to the Include path by default, therefore no need to add them manually.

3. Place the RETARGET functions

The Starter Kits have a bidirectional analog switch between the MCU and the Board Controller.
The VCOM_ENABLE pin should be in high logical state for allowing the data flow through to the board controller.
Find the given pin in the User's Guide of the kit.

Figure 3.
Virtual COM Port Interface.

To realize this setting, add the below lines prior to call the RETARGET functions.
Additional headers added:

    #include "em_cmu.h"
    #include "em_gpio.h"
    #include "retargetserial.h"
    #include "stdio.h"

and place the following code after the CHIP_Init()

  //Enable GPIO clk prior to write its registers  
  CMU_ClockEnable(cmuClock_GPIO,true);

  //Enable the switch with VCOM_ENABLE pin, see User's Guide of the board
  GPIO_PinModeSet(gpioPortA,5,gpioModePushPull,1);

  RETARGET_SerialInit();
  RETARGET_SerialCrLf(1);

  printf("VCOM is working!\n");

4. Start a terminal emulator

Used serial port can be determined by Device Manager:

Figure 4.
Device Manager.

5. Build and download the image

Figure 5.
Terminal on Host PC.

IAR makes it relatively easy to locate an initialized variable in flash. One use-case of this might be to set the Debug Lock Word (DLW) in the lock bits page to lock debug access to the device.

To locate a variable in IAR, you can use the @ sign.

uint32_t myVar @ 0x2000000;

Only 'const' variables can be located and initialized however:

uint32_t const myVar @ 0x00001000 = 0x0000AABB;

Finally, in order to keep variables that will otherwise be unused, they must be declared as '__root'. So, to clear the debug lock word purely with a global variable statement:

__root uint32_t const DLW @ (LOCKBITS_BASE + (127*4)) = 0xFFFFFFF0;

Make sure that, after flashing the device, the device is reset appropriately to engage the debug lock.

To clear the debug lock word from executing code, see the following example: https://github.com/SiliconLabs/peripheral_examples/tree/master/series1/msc/debug_lock

This knowledge base article demonstrates low power operation of the EFM32TG11 using LESENSE to measure movement (rotations and direction) of a half metal disc, similar to what would be used in a water or gas meter. This article includes a software project, and schematic and layout files for an expansion board that connects to the EFM32TG11 STK (SLSTK3301A).
For more information on LESENSE and a software example for Series 0 devices, see AN0029: Low Energy Sensor Interface - Inductive Sense.

Hardware Design

This example uses the SLSTK3301A starter kit for the EFM32TG11, and a custom PCB that connects to the expansion header.  The board has two LC tanks, like the one on the STK, and a 3" half disc mounted to the board with RC car bearings and axles (Traxxas 5116 and Traxxas 6853X). There are also footprints to place two hall effect sensors (Si7204 or Si7210) under the disc, although theseare not implemented in this design.

The two tanks on the expansion board are driven by the main output of DAC0 CH0. These two tanks, and the one on the board share the excite pin (PB11). All tanks can be sampled in this configuration. To use PB11 as LESENSE_EXCITE, a wire needs to be connected to the lower half of R198, to a 100 ohm resistor. The other end of the resistor should be connected to W14. A 0.1 uF capacitor should also be connected from W14 to ground.

A third tank circuit is present on the STK. While it is not used to detect disc rotation, some tamper detection methods use a third tank, so the STK tank is measured to demonstrate that capability. When metal is detected next to this tank, a gecko symbol is drawn on the LCD screen.

The most power efficient settings are to have the DAC triggered by LESENSE. This way the DAC is only enabled when needed. Regular or alternate DAC outputs can be used. Routing the DAC signal through APORT is not recommended as the APORT has higher output impedance.

In order to reduce interference between the tanks, LESENSE pins that are not being scanned can be set to the DAC voltage. Since the tank is connected to the DAC on one side, setting the other side to the DAC voltage will result in no voltage drop across the tank. This reduces coupling between the tanks. This is accomplished by setting the channel idle mode to lesenseChPinIdleDACC. Note that this only works for pins that are an alternate output of the DAC channel being used. For DAC channel 0, this is PC0, PC1, PC2, and PC3. For DAC channel 1, this is PC12, PC13, PC14, and PC15.

Software Design

Once initialized, the main tasks of the application are handled by LESENSE without software execution. LESENSE can run in EM2 while clocked from the LFXO. LESENSE implements quadrature decoding with the decoder state machine. The decoder uses PRS to send signals to PCNT, which maintains the count of rotations. The main loop handles updating the LCD display (triggered from a periodic cryotimer interrupt), and detecting button presses to cycle through display modes.

The LESENSE module uses a sliding window to evaluate the output of the ACMP counter and convert the count into a binary result. This helps compensate for variations in the tank circuit (caused by variances in component values, for example) and removes the requirement that the tanks not be near metal when the device is calibrated.

Current Consumption

When scanning at 16 Hz and sampling 3 tanks, with the LCD off, the average current consumption is 3.5 uA. Enabling the LCD adds about 2 uA of current consumption to power the LCD as well as to do the calculations to generate the strings to display (sprintf).

In this configuration, the marginal consumption of an additional tank is about 100 nA. In cases where a tank needs to be sampled very infrequently, it may be feasible to have a periodic interrupt enable a channel and enable the decoder interrupt. During the decoder interrupt, the tank result can be measured, and the channel and decoder interrupt can be disabled until next time.

Tamper Detection

Only two tanks are required for quadrature decoding of a disc. Typically, half of the disc is made of metal and the tanks are placed 90 degrees apart. With only 90 degrees of the disc's rotation is monitored by the tanks, there is a period where the disc is not detected by either coil. Removing the disc entirely would be indistinguishable from the disc stopping in this position. This would allow unbilled use of the meter. To prevent this, a third tank can be used so that at least one tank is covered at any time. The third tank does not need to be
sampled as often as the first two. See the performance section for tradeoffs in sampling rate. It is also possible to implement a state machine that monitors more than two coils and has a state for tampering detected.

Debugging

Because most of the work this application does is handled by the LESENSE state machine, traditional debugging with breakpoints and stepping is not very effective. Components can be tested one stage at a time (LESENSE counts, scan results, decoder state, PCNT) by reading the registers, or directing the output to an IO pin (for example, PRS signals from the DECODER can be measured at IO pins to verify the DECODER is operating correctly, then the PRS signals can be sent to the PCNT module).

An oscilloscope is useful to monitor the tank oscillations, DAC output voltage, and timing of the excite signals. Note that the capacitance of the scope probe will have an influence on the circuit and may prevent it from operating normally. If a scope probe has multiple gain modes, the capacitance is typically less in the higher gain mode (this can be compensated for by the oscilloscope).

Putting the DAC into a lower power mode where it is driven infrequently can cause it to be more susceptible to noise or interference from scope probes or from pins being touched by a person. When diagnosing issues, the DAC can temporarily be set to continuous conversion mode to prevent these issues. Continuous conversion mode will have much higher current consumption.

Conclusion

This application was developed on an EFM32TG11 (Series 1). Porting to other Series 1 devices that have VDAC and LESENSE is straightforward. The firmware uses emlib for most of the configuration, ensure the availability of DAC alternate output on LESENSE pins.

The DAC peripheral has changed significantly since Series 0. For an example of LC sensing implemented on Series 0 see AN0029.  There are currently no Series 2 devices with LESENSE.

See AN0029 for a more detailed explanation of LESENSE and a software example for Series 0. See the software example SLSTK3301A_helges_demo for another software example that uses LESENSE on an EFM32TG11 STK to detect metal near the onboard tank of the STK.

Malloc is a function provided by the C standard library which is used to dynamically allocate memory. It uses a low-level memory management function, called sbrk, to determine if the heap has available space.  Silicon Labs provides a simple implementation of sbrk, designed for compatibility between all projects. Due to this, it can exhibit a strange behavior where calls to malloc will not return a NULL, even if the heap is full. If an application requires dynamic memory allocation, sbrk will need to be modified to prevent this issue.

For bare-metal applications:

A sample sbrk implementation, which should work with most MCU projects, is provided below. This implementation checks the MSP to determine how much stack space is available. To add this implementation to a project, open “retargetio.c”, which is usually found in the folder “hal-efr32”. Find the sbrk implementation within that file and replace it with the one found below.

#include <sys/stat.h>
extern char _end; /**< Defined by the linker */
caddr_t _sbrk(int incr)
{
  static char *heap_end;
  char *prev_heap_end;

  if (heap_end == 0) {
    heap_end = &_end;
  }

  prev_heap_end = heap_end;
  if ((heap_end + incr) > (char*) __get_MSP()) {
    //errno = ENOMEM;
    return ((void*)-1); // error - no more memory
  }
  heap_end += incr;

  return (caddr_t) prev_heap_end;
}

This example may not work for every example application since different applications configure memory differently. For example, the Bluetooth stack puts the stack at the beginning of RAM, so the MSP can not be used to determine the end of the heap. For this setup, you will need to use an sbrk implementation like the one below. This implementation uses "__HeapLimit", which is defined by the linker, to determine where the heap ends.

#include <sys/stat.h>
extern char _end;         /**< Defined by the linker */
extern char __HeapLimit;  /**< Defined by the linker */
caddr_t _sbrk(int incr)
{
  static char *heap_end;
  char *prev_heap_end;

  if (heap_end == 0) {
    heap_end = &_end;
  }

  prev_heap_end = heap_end;
  if ((heap_end + incr) > (char*) &__HeapLimit) {
    //errno = ENOMEM;
    return ((void*)-1); // error - no more memory
  }
  heap_end += incr;

  return (caddr_t) prev_heap_end;
}

In general, keep your application's memory layout in mind when using malloc, and modify sbrk to fit.

For RTOS applications:

The above implementations of sbrk can be used in a multi-threaded environment, but with the caveat that they are not thread-safe. This can be circumvented by wrapping calls to memory management functions in critical sections. Additionally, most RTOSes will provide implementations of dynamic memory allocation. For example, MicirumOS provides a memory management API that can be used instead of the standard library implementations.

1. Abbreviations

• SDK - Software Development Kit
• HAL - Hardware Abstraction Layer
• KBA - Knowledge Base Article
• ROS - Robot Operating System
• SLSTK, SLSTK3701A - Giant Gecko Starter Kit

2. Configuration

• Board:
  • EFM32GG11B STK - BRD2204A Rev BD4 (SLSTK3701A)
• Development:
  • Windows 10 OS
  • Simplicity Studio V4.
  • 32-bit MCU SDK Version: 5.6.1.0
• Execution:
  • Ubuntu 16.04 LTS
  • ROS Kinetic

3. Preface

The ROS is one of the most known robot platform which hobbyist uses for their robot projects. Furthermore, based on the ROS related widespread libraries, the user community, and the well-structured documentation, usage of the ROS expanded to the industrial participants too. ROS' name refers to an operating system, but it is not truly an operating system, instead, ROS is a framework which should be installed and configured to run on Linux operating system. The official ROS releases recommend that the developers should install these frameworks to one of Linux Ubuntu distros. As regards of the resource consumption of Ubuntu distributions, the ROS cannot be run on low resource based MCUs (like Cortex M, Atmel 8bit, etc.), so the developer should use appropriate devices to run Ubuntu. These devices can be regular PC's, laptops or board computers (e.g.: Raspberry Pi). At this point the reader probably has a question: why is it useful using of low power MCUs when the ROS cannot be run on them. And the answer is: these MCUs are used as expansions of the ROS’ host computer. An MCU can easily initiate a connection with a sensor, collect the data of this sensor and at the end send the collected data to the host PC where the data will be processed. The officially supported MCUs are listed on the ROS website, and it is also described how a not supported one can be added. This KBA will give a high-level description with an example about how EFM32 or EFR32 MCUs can be transformed to a ROS Serial Node.

4. What can the reader expect from this KBA

This KBA will not explain: ROS related base concepts. The readers who are not familiar with those words in ROS environment like roscore, node, topic, etc. should take the first steps on the ROS website. The intent of this KBA is describing the process of how a developer can append a not officially ROS supported MCU to ROS environment. The description will not start from the scratch: the ROS related chapter about how a new MCU can be added, the Arduino related source codes and the Silabs related SDK will be used for the development. The previously used "development" word can be divided to two parts: in the first part the ROS related hardware driver will be implemented, in the second part an available Arduino based ROS end node project will be ported to the previously implemented end node.

5. ROS serial node

The serial node's operation is very primitive: the communication between the host PC and MCU is performed via UART. This communication is defined by ROS, the ROS library has module which defines it. Before the MCU starts to exchange data between itself and the host PC, the MCU has to convert the data to a predefined structure, which called "messages". These messages also have modules in the ROS library, so they can be just used. The following picture will visualize the high-level structure of the implemented serial node.

5.1 ROS library - HW linking layer

The description starts with the middle layer, because it is the key element contributing to the operation of the node. Check the following site for initial description: (http://wiki.ros.org/rosserial_client/Tutorials/Adding%20Support%20for%20New%20Hardware) All lower layers, software and hardware, shall be encapsulated into the following 4 methods, and upper ROS layers, like ROS library and ROS application will use these methods:

class Hardware
{

  Hardware();

  // any initialization code necessary to use the serial port
  void init(); 

  // read a byte from the serial port. -1 = failure
  int read()

  // write data to the connection to ROS
  void write(uint8_t* data, int length);

  // returns milliseconds since start of program
  unsigned long time();

};

The reader can find the SLWSTK3701 related class file in the attached project, with the following path and name: /ros_lib/ros/SLSTK3701AHardware.h. Another specialty of this layer is that it is a mixture of the c and the c++ programming language. The HAL layer has been written in C, but the ROS related layers require C++ methods and classes.

Explanation of the functions:

void init():

This method is responsible for the initialization of the hardware, the MCU and the MCU related peripherals. It has 2 mandatory items which shall be initialized:

• a TIMER peripheral, which will be the base of the time() method and
• an USART peripheral, which will be the base of read() and write() methods.

int read():

Read() method is responsible for receiving the data which has been sent by the host PC. The ROS Lib processes the received data in asynchronous mode, therefore the plain USART_Rx() function had to be expanded with a circular buffer. This buffer was not part of the ROS Lib, so it has been implemented, too. The circular buffer has been placed under the \utils\ringbuffer_class folder.

void write():

Write() method is the opposite of the read() regarding the functionality. Its only one role is place data to the used USART line. The host side (PC side) can receive this data without any additional buffering method, providing the host side implements it.

unsigned long time():

Return value of this method shall be incremented with one after each elapsed millisecond.

The following figure highlights where the Linking Layer is placed in the Simplicity Studio project structure.

Figure 2 - Linking layer location

5.2 ROS library

The ROS library has been downloaded from the ROS website, which marked as Arduino library. The necessary modules for the operation of the example application are attached for the example project. These files can be found under ros_lib/ path.

Figure 3 - ROS Lib location

5.3 Application

In this chapter, we will examine the operation of the base application (which is one of the original Arduino ROS examples), the ported application and at the end, we will compare them. The chosen application is one of the simplest Arduino related ROS_lib example which name is: blink. The expected operation of the original Arduino example is:

• build the application and upload it to an Arduino Uno
• connect the Arduino to the host computer of ROS
• enter to a terminal: roscore
• enter to another terminal: rosrun rosserial_python serial_node.py /dev/ttyUSBn
• enter to a 3rd terminal: rostopic pub toggle_led std_msgs/Empty –once

The last task can be done more times. Each repetition will cause blinking of the Arduino's LED.

The following figure compares the codes used for of Arduino and the one used for of Simplicity Studio.

Figure 4 - Comparasion of the 2 source codes

In case of SLSTK3701A, the operation will be the same as the original one, but there are differences with the setup. In steps:

• the first thing is: compile the attached project and upload the compiled *.hex file to the SLSTK
• then connect the SLSTK to the host computer, according to the following description: the ROS node initialized as to use the USART0 peripheral, which means ROS node uses the extension header related pins. The pin 4 works as Rx and the pin 6 is the Tx. I used one of the Silabs developed USART - USB converters to establish the connection between the SLSTK and the host PC, but any other appropriate device can be used.
• after the previous point the steps to take for Arduino and STK are same, so enter to a terminal: roscore
• enter to another terminal: rosrun rosserial_python serial_node.py /dev/ttyUSBn
• enter to a 3rd terminal: rostopic pub toggle_led std_msgs/Empty –once

5.4 HAL (Peripheral drivers)

It is Silabs SDK related peripheral drivers. The following figure highlights the used HAL elements for the project.

Figure 5 - HAL location

5.5 HW - EFM32GG11B_SLSTK3701A

The used development board is one of the Silicon Lab's flagship models. The ability of the EFM32GG11B is much higher than the used application requirements, but this MCU and development board is the most known board, therefore this one used for this demo project.