Skip to content

Commit

Permalink
Update PlatformIO.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@MCUdude
MCUdude committed Nov 17, 2020
1 parent 96f4a0a commit af30972
Showing 1 changed file with 116 additions and 53 deletions.
169 changes: 116 additions & 53 deletions PlatformIO.md
View file
Expand Up @@ -14,71 +14,113 @@ And best of all, MiniCore is supported!
## MiniCore + PlatformIO
MiniCore 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.
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:

You can find a platformio.ini template you can use when creating a project for a MiniCore 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
; Only set fuses
pio run -t fuses -e fuses_bootloader
; Set fuses and burn bootloader
pio run -t bootloader -e fuses_bootloader
; (where "fuses_bootloader" can be replace with a different environment to match your build configuration)
```

You can find a platformio.ini template you can use when creating a project for a MiniCore compatible device below.
The most common functionality is available in this template. As you can see, the templated is divided into multiple environments.

* The default build environment are defined under `[platformio]`.
* All parameters that are common for all environments are defined under `[env]`.
* Use `[env:Upload_UART]` or `[env:Upload_ISP]` to upload to your target.
* Use `[env:fuses_bootloader]` to set the fuses or burn the bootloader.

More information on what each line means can be found futher down on this page.


## platformio.ini template

``` ini
; PlatformIO template project configuration file for MiniCore
; PlatformIO Project Configuration File for MiniCore
; https://github.com/MCUdude/MiniCore/
;
; 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
;
; Please visit documentation for the other options
; https://github.com/MCUdude/MiniCore/blob/master/PlatformIO.md
; https://docs.platformio.org/page/projectconf.html
; https://docs.platformio.org/en/latest/platforms/atmelavr.html


; ENVIRONMENT SETTINGS
[env:MiniCore]
[platformio]
default_envs = Upload_UART ; Default build target


; Common settings for all environments
[env]
platform = atmelavr
framework = arduino

; TARGET SETTINGS
; PlatformIO requires the board parameter. Must match your actual hardware
; Chip in use
board = ATmega328P
; 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
; Comment out to enable LTO (this line unflags it)
build_unflags = -flto
; Extra build flags
build_flags =

; Upload using programmer
;upload_protocol = usbasp
; Aditional upload flags
;upload_flags = -Pusb

; SERIAL MONITOR OPTIONS
; Monitor and upload port is the same by default
;monitor_port =
; Serial monitor port defined in the Upload_UART environment
monitor_port = ${env:Upload_UART.upload_port}
; Serial monitor baud rate
monitor_speed = 9600


; Run the following command to upload with this environment
; pio run -e Upload_UART -t upload
[env:Upload_UART]
; Serial bootloader protocol
upload_protocol = arduino
; Serial upload port
upload_port = /dev/cu.usbserial*
; Get upload baud rate defined in the fuses_bootloader environment
board_upload.speed = ${env:fuses_bootloader.board_bootloader.speed}


; Run the following command to upload with this environment
; pio run -e Upload_ISP -t upload
[env:Upload_ISP]
; Custom upload procedure
upload_protocol = custom
; Avrdude upload flags
upload_flags =
-C$PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
-p$BOARD_MCU
-PUSB
-cusbasp
; Avrdude upload command
upload_command = avrdude $UPLOAD_FLAGS -U flash:w:$SOURCE:i


; Run the following command to set fuses
; pio run -e fuses_bootloader -t fuses
; Run the following command to set fuses + burn bootloader
; pio run -e fuses_bootloader -t bootloader
[env:fuses_bootloader]
board_hardware.oscillator = external ; Oscillator type
board_hardware.uart = uart0 ; Set UART to use for serial upload
board_bootloader.speed = 115200 ; Set bootloader baud rate
board_hardware.bod = 2.7v ; Set brown-out detection
board_hardware.eesave = yes ; Preserve EEPROM when uploading using programmer
upload_protocol = usbasp ; Use the USBasp as programmer
upload_flags = ; Select USB as upload port and divide the SPI clock by 8
-PUSB
-B8

```


Expand Down Expand Up @@ -164,42 +206,61 @@ Specifies if the EEPROM memory should be retained when uploading using a program
| `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`.

**Note that if you're using a programmer that communicates with Avrdude with a serial port (Arduino as ISP, STK500, etc.) the `board_upload.speed` field will interfere with the programmer's baud rate. In this case, use `board_bootloader.speed` to set the bootloader baud rate, and `board_upload.speed` to set the baud rate for the programmer.**
### `board_hardware.ckout`
Enable clock output on pin PB0 on targets that supports it (ATmega48/88/168/328).

| Clock output enable |
|---------------------|
| `yes` |
| `no` (default) |


### `board_hardware.cfd`
Enable clock failure detection. The internal 1 MHz oscillator will kick in if the external oscillator fails (only available on ATmega328PB).

Recommended baud rate for the particular clock speed is in **bold text**.
| Clock failure detection |
|-------------------------|
| `yes` |
| `no` (default) |

### `board_upload.speed`

### `board_upload.speed` / `board_bootloader.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*.

**Note that if you're using a programmer that communicates with Avrdude with a serial port (Arduino as ISP, STK500, etc.) the `board_upload.speed` field will interfere with the programmer's baud rate.
In this case, use `board_bootloader.speed` to set the bootloader baud rate, and `board_upload.speed` to set the baud rate for the programmer.**

Recommended baud rate for the particular clock speed is in **bold 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* |
| `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** |


### `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:

### `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:

| Flag | Default size | Description |
|-----------------------------|--------------|-----------------------------------------------------------|
| -lprintf_flt | | Lets you print floats with printf (occupies ~1.5 kB) |
| -Wall -Wextra | | Show all compiler warnings |
| -DSERIAL_RX_BUFFER_SIZE=128 | 64 bytes | Sets the serial RX buffer to 128 bytes |
| -DSERIAL_TX_BUFFER_SIZE=128 | 64 bytes | Sets the serial TX buffer to 128 bytes |
| -DTWI_BUFFER_SIZE=64 | 32 bytes | Sets the TWI (i2c) buffer to 64 bytes |
Expand All @@ -223,14 +284,16 @@ Used to pass extra flags to Avrdude when uploading using a programmer.
Typical parameters are `-PUSB`, `-B[clock divider]` and `-b[baudrate]`.
**Note that every flag has to be on its own line, and they have to be indented with two spaces:**
```ini
upload_flags = -PUSB
upload_flags =
-PUSB
-B32
-v
```


### `monitor_port`
PlatformIO detects serial ports automatically. However, if you want to override this you can uncomment `monitor_port`. Use `/dev/[port]` on Unix compatible systems, and use `COMx` on Windows.
PlatformIO detects serial ports automatically. However, In the template above it uses the upload port defined in the `env:Upload_UART` environment.
if you want to override this you can insert your upload port here. Use `/dev/[port]` on Unix compatible systems, and use `COMx` on Windows.


### `monitor_speed`
Expand Down

0 comments on commit af30972

Please sign in to comment.