# Overview

libtungsten is a simple and open-source library designed to help you program ARM Cortex microcontrollers. Let's talk about some key aspects :

### Open mindset

Open source is more than just a license, it's a mindset. Unlike some other popular libraries, the code of libtungsten isn't hidden deep inside the OS, trying to keep beginners and hackers from seeing it : instead, it is available right there in your project folder, inviting you to see how it works and to customize it to fit your needs.

### Opening the black box

Microcontroller programming can sometimes look a bit like dark magic to beginners in the way software is able to interract with hardware. « What's inside this digitalWrite() function that allows it to act on my electrical circuit and light up this LED? » is the kind of question most programmers ask themselves at least once. libtungsten provides easily accessible and well-documented code that you can simply go read if you want to learn more. The documentation also features in-depth tutorials explaining the internal workings of the microcontroller as well as how to read the datasheets. All these resources are here so you can truly learn how things work.

### Customizing

Keeping a copy of the library inside each project also means that it can be customized for each application. Found the perfect sensor for your project but it requires unusual I2C settings? Not a problem, just open the i2c.cpp driver and customize it to fit your needs. Want to control a strip of WS2812 RGB LEDs without wasting tons of CPU cycles? Write a custom driver based on spi.cpp to use the SPI controller and the DMA. Need to use the SysTick system timer for an advanced application-specific purpose? Just open core.cpp and customize it at will. To get you started, the documentation of each module contains a Hacking section giving tips and ideas about what can be customized. By the way, if you cloned the library from the Git repository and you want to update it, don't worry, Git will be able to merge your changes in the new version.

### Which microcontroller are we talking about?

In order to keep things simple libtungsten does not try to be generic and portable across lots of microcontrollers; instead, it is dedicated to the ATSAM4L line of microcontrollers from Atmel/Microchip. These microcontrollers come in a range of sizes (48, 64 and 100 pins), packages (TQFP, VFBGA, WLCSP and QFN), and memory density (32Kb RAM / 128Kb Flash, 32Kb RAM / 256Kb Flash and 64Kb RAM / 512Kb Flash). They are based on the Cortex M4 architecture, can run up to 48MHz, have a lot of optimizations for low-power design and come with loads of interesting peripherals, such as :

• Powerful interrupt controller
• DMA (Direct Memory Access) controller
• USB interface, both Device and Host
• USART (also known as Serial or RS232), I2C and SPI controllers
• ADC (Analog to Digital Converter) and DAC (Digital to Analog Converter)
• timers/counters
• touchscreen controller
• stereo audio output
• parallel capture
• random number generator
• Glue Logic controller
• and more ...

### Requirements

Obviously, in order to program a microcontroller, a library is not enough : you need a board equipped with the microcontroller in question. You have basically three options, from easiest to hardest :

• using a Carbide, an open-source board specifically designed for libtungsten : you can learn more here
• using an evaluation board from Atmel based on the ATSAM4L, such as the SAM4L Xplained Pro (which you can find in usual electronics stores such as Farnell or Mouser, or even on Ebay)
If you use a Carbide with a preloaded bootloader or an Xplained Pro, you can start right away. Otherwise, in order to program and debug that board, you will need a JTAG/SWD adapter (some kind of USB device that is able to take control of a microcontroller), such as the Atmel ICE or the IBDAP. More info about that in the JTAG/SWD vs Bootloader tutorial.

libtungsten is released under the permissive Apache 2.0 license, which basically means that you can use the library freely for personnal and commercial use. More information about this on the official page, or on TLDRLegal for a more digestible version.

# Philosophy

libtungsten adopts the Unix philosophy stating that a tool should do only one thing, but do it well. In that perspective, it doesn't offer an IDE but instead invites you to use the text editor of your choice, whether it is console-based (vim, emacs... in no particular order) or GUI-based (Sublime Text, ...). Compiling and flashing code is done using a simple Makefile and OpenOCD (by default, you can use something else if you prefer).

The library aims to be as light, simple and straightforward as possible :

• plain standard C++11
• no obscure preprocessor macro
• only one line of microcontrollers supported, no complicated compatibility hacks
• direct correspondence between the library's code (in terms of modules, also sometimes called drivers) and the microcontroller datasheet (in terms of peripherals)
• every module is neatly organized in a dedicated namespace, and functions are accessed with the standard scope resolution operator : Module::function()

Most of the microcontroller's peripherals offer powerful but complex features which can be optimized in very specific situations. To keep things simple, the library doesn't try to accomodate every possible case; instead, you are free to customize the modules to fit your needs.