diff --git a/PlatformIO.md b/PlatformIO.md index 34288cab5..5b809f5c8 100644 --- a/PlatformIO.md +++ b/PlatformIO.md @@ -1,7 +1,7 @@ # PlatformIO [PlatformIO](https://platformio.org) is an open source ecosystem for embedded development. -It has a built-in library manager and is Arduino compatible. It supports most operating systems; Windows, MacOS, Linux 32 and 64-bit; ARM and X86. +It has a built-in library manager and is Arduino compatible. It supports most operating systems; Windows, MacOS, Linux 32 and 64-bit, ARM and X86. And best of all, MightyCore is supported! * [What is PlatformIO?](http://docs.platformio.org/en/latest/what-is-platformio.html) @@ -12,16 +12,20 @@ And best of all, MightyCore is supported! ## MightyCore + PlatformIO -At the moment it is not possible to burn the bootloader or set fuses using PlatformIO. You will still have to use Arduino IDE for this. -However, PlatformIO really shows its stength when working on large projects, often with a lot of dependencies. -I've made a simple platformio.ini template you can use when creating a project for a MightyCore compatible device. The most common functionality is available through this template. -For more information about the `build` option, check out PlatformIO's [Project Configuration File Doc page](https://docs.platformio.org/page/projectconf.html). +MightyCore and PlatformIO goes great together. You can do serial uploads and upload using a dedicated programmer, but you can also let PlatformIO calulate the fuses and load the correct bootloader file, just like Arduino IDE does! + +PlatformIO uses the information provided in platformio.ini to calculate what fuse bits and what bootloader file to load. Simply provide enough information and run the following commands: +`pio run --target fuses` to only set the fuses +`pio run --target bootloader` to set the fuses and burn the bootloader. + +You can find a platformio.ini template you can use when creating a project for a MightyCore compatible device below. The most common functionality is available in this template. More information on what each line means can be found futher down on this page. ``` ini -; PlatformIO Project Configuration File for MightyCore +; PlatformIO template configuration file for MightyCore ; https://github.com/MCUdude/MightyCore/ ; ; Build options: build flags, source filter +; Hardware options: oscillator type, BOD, UART number, EEPROM retain ; Upload options: custom upload port, speed, and extra flags ; Library options: dependencies, extra library storages ; Advanced options: extra scripting @@ -29,6 +33,7 @@ For more information about the `build` option, check out PlatformIO's [Project C ; Please visit documentation for the other options ; https://github.com/MCUdude/MightyCore/blob/master/PlatformIO.md ; https://docs.platformio.org/page/projectconf.html +; https://docs.platformio.org/en/latest/platforms/atmelavr.html ; ENVIRONMENT SETTINGS @@ -42,6 +47,21 @@ board = ATmega1284P ; Clock frequency in [Hz] board_build.f_cpu = 16000000L +; HARDWARE SETTINGS +; Oscillator option +board_hardware.oscillator = external +; Hardware UART for serial upload +board_hardware.uart = uart0 +; Brown-out detection +board_hardware.bod = 2.7v +; EEPROM retain +board_hardware.eesave = yes + +; UPLOAD SETTINGS +board_upload.speed = 115200 +; Upload serial port is automatically detected by default. Override by uncommenting the line below +;upload_port = /dev/cu.usbserial* + ; BUILD OPTIONS ; Current pinout board_build.variant = mightycore_standard @@ -50,12 +70,6 @@ build_unflags = -flto ; Extra build flags build_flags = -; UPLOAD SETTINGS -; Upload serial port is automatically detected by default. Override by uncommenting the line below -;upload_port = /dev/cu.usbserial* -; Upload baud rate -board_upload.speed = 115200 - ; Upload using programmer ;upload_protocol = usbasp ; Aditional upload flags @@ -73,51 +87,119 @@ monitor_speed = 9600 PlatformIO requires the `board` parameter to be present. The table below shows what board name should be used for each target -| Target | Board name | -|------------------------------------------------|-------------| -| ATmega1284P | ATmega1284P | -| ATmega1284 | ATmega1284 | -| ATmega644P/PA | ATmega644P | -| ATmega644/A | ATmega644A | -| ATmega324PB | ATmega324PB | -| ATmega324PA | ATmega324PA | -| ATmega324P | ATmega324P | -| ATmega324A | ATmega324A | -| ATmega164P/PA | ATmega164P | -| ATmega164A | ATmega164A | -| ATmega32 | ATmega32 | -| ATmega16 | ATmega16 | -| ATmega8535 | ATmega8535 | +| Target | Board name | +|------------------------------------------------|---------------| +| ATmega1284P | `ATmega1284P` | +| ATmega1284 | `ATmega1284` | +| ATmega644P/PA | `ATmega644P` | +| ATmega644/A | `ATmega644A` | +| ATmega324PB | `ATmega324PB` | +| ATmega324PA | `ATmega324PA` | +| ATmega324P | `ATmega324P` | +| ATmega324A | `ATmega324A` | +| ATmega164P/PA | `ATmega164P` | +| ATmega164A | `ATmega164A` | +| ATmega32 | `ATmega32` | +| ATmega16 | `ATmega16` | +| ATmega8535 | `ATmega8535` | ### `board_build.f_cpu` -Holds the main clock frequency in [Hz]. -Note that the clock frequency and upload baud rate will have to match if uploading using a serial bootloader. -Below is a table with the default clocks and baud rates for MightyCore: - -| Clock speed | Oscillator | board_build.f_cpu | board_upload.speed | -|-------------|------------|-------------------|--------------------| -| 20 MHz | External | 20000000L | 115200 | -| 18.4320 MHz | External | 18432000L | 115200 | -| 16 MHz | External | 16000000L | 115200 | -| 14.7456 MHz | External | 14745600L | 115200 | -| 12 MHz | External | 12000000L | 57600 | -| 11.0592 MHz | External | 11059200L | 115200 | -| 8 MHz | External | 8000000L | 57600 | -| 7.3728 MHz | External | 7372800L | 115200 | -| 3.6864 MHz | External | 3686400L | 115200 | -| 1.8432 MHz | External | 1843200L | 115200 | -| 8 MHz | Internal | 8000000L | 38400 | -| 1 MHz | Internal | 1000000L | 9600 | +Specifies the clock frequency in [Hz]. +Used to determine what oscillator option to choose. A capital L has to be added to the end of the frequency number. +Below is a table with supported clocks for MiniCore. Defaults to 16 MHz if not specified. + +| Clock speed | Oscillator | board_build.f_cpu | +|-------------|------------|---------------------------| +| 20 MHz | External | `20000000L` | +| 18.432 MHz | External | `18432000L` | +| 16 MHz | External | `16000000L` (default) | +| 14.7456 MHz | External | `14745600L` | +| 12 MHz | External | `12000000L` | +| 11.0592 MHz | External | `11059200L` | +| 8 MHz | External | `8000000L` | +| 7.3728 MHz | External | `7372800L` | +| 3.6864 MHz | External | `3686400L` | +| 1.8432 MHz | External | `1843200L` | +| 8 MHz | Internal | `8000000L` | +| 1 MHz | Internal | `1000000L` | + + +### `board_hardware.oscillator` +Spefices to use the internal or an external oscillator. +Internal oscillator only works with `board_build.f_cpu` values `8000000L` and `1000000L`. + +| Oscillator option | +|----------------------| +| `external` (default) | +| `internal` | + + +### `board_hardware.uart` +Specifies the hardware UART port used for serial upload. Use `no_bootloader` if you’re using a dedicated programmer, i.e not using a bootloader for serial upload. + +| Upload serial port option | +|---------------------------| +| `no_bootloader` | +| `uart0` (default) | +| `uart1` | +| `uart2` (324PB only) | + + +### `board_hardware.bod` +Specifies the hardware brown-out detection. Use `disabled` to disable. + +| ATmega164/324/644/1284 | ATmega8535/16/32 | +|------------------------|------------------| +| `4.3v` | `4.0v` | +| `2.7v` (default) | `2.7v` (default) | +| `1.8v` | | +| `disabled` | `disabled` | + + +### `board_hardware.eesave` +Specifies if the EEPROM memory should be retained when uploading using a programmer. Use `no` to disable. + +| EEPROM retain | +|-----------------| +| `yes` (default) | +| `no` | + + +### `board_upload.speed` +Specifies the upload baud rate. Available baud rates is shown in the table below, had has to corrolate with `build_board.f_cpu`. +Recommended baud rate for the particular clock speed is in *italic text*. + +| | 1000000 | 500000 | 460800 | 250000 | 230400 | 115200 | 57600 | 38400 | 19200 | 9600 | +|-------------|---------|--------|--------|--------|--------|--------|--------|--------|-------|--------| +| `20000000L` | | X | | X | | *X* | | | X | | +| `18432000L` | | | X | | X | *X* | X | X | X | X | +| `16000000L` | X | X | | X | | *X* | | X | X | X | +| `14745600L` | | | X | | X | *X* | X | X | X | X | +| `12000000L` | | X | | X | | | *X* | | X | X | +| `11059200L` | | | X | | X | X | *X* | X | X | X | +| `8000000L` | X | X | | X | | X | X | *X* | X | X | +| `7372800L` | | | X | | X | *X* | X | X | X | X | +| `3686400L` | | | X | | X | *X* | X | X | X | X | +| `1843200L` | | | | | X | *X* | X | X | X | X | +| `1000000L` | | | | | | | | | | *X* | ### `board_build.variant` -Holds the current pinout in use. Valid pinouts is `mightycore_standard`, `mightycore_bobuino` and `mightycore_sanguino`.
+Holds the current pinout in use. See [pinout pics](https://github.com/MCUdude/MightyCore#pinout) for more info. +| Pinouts | +|---------------------------------| +| `mightycore_standard` (default) | +| `mightycore_bobuino` | +| `mightycore_sanguino` | + + ### `build_unflags` This parameter is used to unflag. Since LTO is enabled by default in PlatformIO we may disable it by unflagging `-flto`. + ### `build_flags` This parameter is used to set compiler flags. This is useful if you want to for instance want to chage the serial RX or TX buffer. Here's a list of the current available core files flags: