From 8a98bf52608a0188fb09ada109c3902795462019 Mon Sep 17 00:00:00 2001 From: Bas Stottelaar Date: Sun, 12 Jan 2020 21:31:12 +0100 Subject: [PATCH] boards/ikea-tradfri: add board documentation. --- boards/ikea-tradfri/doc.txt | 167 +++++++++++++++++++++++++++++++++++- 1 file changed, 164 insertions(+), 3 deletions(-) diff --git a/boards/ikea-tradfri/doc.txt b/boards/ikea-tradfri/doc.txt index 8773486740..2ae0a5ad5b 100644 --- a/boards/ikea-tradfri/doc.txt +++ b/boards/ikea-tradfri/doc.txt @@ -1,5 +1,166 @@ /** -@defgroup boards_ikea-tradfri IKEA TRÅDFRI modules -@ingroup boards -@brief Support for the IKEA TRÅDFRI modules + * @defgroup boards_ikea-tradfri IKEA TRÅDFRI modules + * @ingroup boards + * @brief Support for the IKEA TRÅDFRI modules + +## Overview +The IKEA TRÅDFRI is a small board found in different IKEA TRÅDFRI products. +The board contains an EFR32 microcontroller and a 2MBit SPI NOR Flash. + +More information about the module can be found on this +[GitHub page](https://github.com/basilfx/TRADFRI-Hacking). + +## Hardware + +## +| MCU | EFR32MG1P132F256GM32 | +|-----------------|-----------------------------------------------------------------------------------------| +| Family | ARM Cortex-M4F | +| Vendor | Silicon Labs | +| Vendor Family | EFR32 Mighty Gecko 1P | +| RAM | 32.0KB (1.0KB reserved) | +| Flash | 256.0KB | +| EEPROM | no | +| Frequency | up to 38.4 MHz | +| FPU | yes | +| MPU | yes | +| DMA | 12 channels | +| Timers | 2x 16-bit + 1x 16-bit (low power) | +| ADCs | 12-bit ADC | +| UARTs | 2x USART, 1x LEUART | +| SPIs | 2x USART | +| I2Cs | 1x | +| Vcc | 1.85V - 3.8V | +| Datasheet | [Datasheet](https://www.silabs.com/documents/public/data-sheets/efr32mg1-datasheet.pdf) | +| Manual | [Manual](https://www.silabs.com/documents/public/reference-manuals/efr32xg1-rm.pdf) | + +### Module versions +There are currently two types of modules available. The older module is labeled +ICC-1 and the newer one ICC-A-1. The main difference, is that pin PF3 is now +used to enable the SPI NOR Flash, and not exposed anymore. + +### Pinout +Pin 1 is on the top-left side with only 6 contacts. + +| | PIN | PIN | | +|------|-----|-----|------| +| | | 16 | RES | +| | | 15 | PF3 | +| PA0 | 1 | 14 | PF2 | +| PA1 | 2 | 13 | PF1 | +| PB12 | 3 | 12 | PF0 | +| PB13 | 4 | 11 | PC11 | +| GND | 5 | 10 | PC10 | +| 3V3 | 6 | 9 | PB14 | +| | | 8 | PB15 | +| | | 7 | GND | + +**Note**: On the ICC-A-1 module, PF3 is not exposed anymore. + +### Peripheral mapping +| Peripheral | Number | Hardware | Pins | Comments | +|------------|---------|-----------------|-----------------------------------|-----------------------------------------------------| +| ADC | 0 | ADC0 | CHAN0: internal temperature | Ports are fixed, 14/16-bit resolution not supported | +| HWCRYPTO | — | — | | AES128/AES256, SHA1, SHA256 | +| RTT | — | RTCC | | 1 Hz interval. Either RTT or RTC (see below) | +| RTC | — | RTCC | | 1 Hz interval. Either RTC or RTT (see below) | +| SPI | 0 | USART1 | MOSI: PD15, MISO: PD14, CLK: PD13 | | +| Timer | 0 | TIMER0 + TIMER1 | | TIMER0 is used as prescaler (must be adjecent) | +| UART | 0 | USART0 | RX: PB15, TX: PB14 | Default STDIO output | + +### User interface +| Peripheral | Mapped to | Pin | Comments | +|------------|-----------|------|----------| +| LED | LED0 | PB13 | | +| | LED1 | PA1 | | + +## Implementation Status +| Device | ID | Supported | Comments | +|------------------|------------|-----------|----------------------------------------------------------------| +| MCU | EFR32MG1P | yes | Power modes supported | +| Low-level driver | ADC | yes | | +| | Flash | yes | | +| | GPIO | yes | Interrupts are shared across pins (see reference manual) | +| | HW Crypto | yes | | +| | I2C | yes | | +| | PWM | yes | | +| | RTCC | yes | As RTT or RTC | +| | SPI | partially | Only master mode | +| | Timer | yes | | +| | UART | yes | USART is shared with SPI. LEUART baud rate limited (see below) | +| SPI NOR Flash | IS25LQ020B | yes | 2MBit flash. Can be used with the the MTD API. | + +## Board configuration + +### Clock selection +There are several clock sources that are available for the different +peripherals. You are advised to read [AN0004](https://www.silabs.com/Support%20Documents/TechnicalDocs/AN0004.pdf) +to get familiar with the different clocks. + +| Source | Internal | Speed | Comments | +|--------|----------|------------|------------------------------------| +| HFRCO | Yes | 19 MHz | Enabled during startup, changeable | +| HFXO | No | 38.4 MHz | | +| LFRCO | Yes | 32.768 kHz | | +| ULFRCO | No | 1.000 kHz | Not very reliable as a time source | + +The sources can be used to clock following branches: + +| Branch | Sources | Comments | +|--------|-------------------------|------------------------------| +| HF | HFRCO, HFXO | Core, peripherals | +| LFA | LFRCO, LFXO | Low-power timers | +| LFB | LFRCO, LFXO, CORELEDIV2 | Low-power UART | +| LFE | LFRCO, LFXO | Real-time Clock and Calendar | + +CORELEDIV2 is a source that depends on the clock source that powers the core. +It is divided by 2 or 4 to not exceed maximum clock frequencies (EMLIB takes +care of this). + +The frequencies mentioned in the tables above are specific for this starter +kit. + +It is important that the clock speeds are known to the code, for proper +calculations of speeds and baud rates. If the HFXO or LFXO are different from +the speeds above, ensure to pass `EFM32_HFXO_FREQ=freq_in_hz` and +`EFM32_LFXO_FREQ=freq_in_hz` to your compiler. + +You can override the branch's clock source by adding `CLOCK_LFA=source` to +your compiler defines, e.g. `CLOCK_LFA=cmuSelect_LFRCO`. + +## Flashing the device +To flash, [SEGGER JLink](https://www.segger.com/jlink-software.html) is +required. + +Flashing is supported by RIOT-OS using the command below: + +``` +make flash +``` + +To run the GDB debugger, use the command: + +``` +make debug +``` + +Or, to connect with your own debugger: + +``` +make debug-server +``` + +Some boards have (limited) support for emulation, which can be started with: + +``` +make emulate +``` + +## Supported Toolchains +For using the IKEA TRåDFRI module we strongly recommend the usage of the +[GNU Tools for ARM Embedded Processors](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm) +toolchain. + +## License information +* Silicon Labs' EMLIB: zlib-style license (permits distribution of source). */