Skip to content

Latest commit

 

History

History
433 lines (277 loc) · 13.6 KB

installation.rst

File metadata and controls

433 lines (277 loc) · 13.6 KB
Raw

Installation

Note

Please note that you do not need to install :ref:`piocore` if you are going to use :ref:`pioide`. :ref:`piocore` is built into PlatformIO IDE and you will be able to use it within PlatformIO IDE Terminal.

If you need :ref:`piocore` outside PlatformIO IDE, please :ref:`piocore_install_shell_commands`.

PlatformIO Core is written in Python and works on Windows, macOS, Linux, FreeBSD and ARM-based credit-card sized computers (Raspberry Pi, BeagleBone, CubieBoard, Samsung ARTIK, etc.).

System requirements

Operating System:

Windows, macOS, Linux, FreeBSD, Linux ARMv6+
Python Interpreter:

Python 2.7 or Python 3.5+. See detailed instruction how to :ref:`faq_install_python` for Windows.
Terminal Application:

All commands below should be executed in Command-line application (Terminal). For macOS and Linux OS - Terminal application, for Windows OS – cmd.exe application.
Access to Serial Ports (USB/UART):

Windows Users: Please check that you have correctly installed USB driver from board manufacturer

Linux Users:

Installation Methods

Please choose ONE of the following methods:

Python Package Manager

The latest stable version of PlatformIO may be installed or upgraded via Python Package Manager (pip) as follows:

pip install -U platformio

If pip command is not available run easy_install pip or use :ref:`installation_installer_script` which will install pip and platformio automatically.

Note that you may run into permissions issues running these commands. You have a few options here:

  • Run with sudo to install PlatformIO and dependencies globally
  • Specify the pip install --user option to install local to your user
  • Run the command in a virtualenv local to a specific project working set.

Installer Script

Super-Quick (Mac / Linux)

To install or upgrade PlatformIO paste that at a Terminal prompt (MAY require administrator access sudo):

python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/develop/scripts/get-platformio.py)"

Local Download (Mac / Linux / Windows)

To install or upgrade PlatformIO, download (save as...) get-platformio.py script. Then run the following (MAY require administrator access sudo):

# change directory to folder where is located downloaded "get-platformio.py"
cd /path/to/dir/where/is/located/get-platformio.py/script

# run it
python get-platformio.py

On Windows OS it may look like:

# change directory to folder where is located downloaded "get-platformio.py"
cd C:\path\to\dir\where\is\located\get-platformio.py\script

# run it
C:\Python27\python.exe get-platformio.py

macOS Homebrew

The latest stable version of PlatformIO may be installed or upgraded via macOS Homebrew Packages Manager (brew) as follows:

brew install platformio

Full Guide

  1. Check a python version:
python --version

If Python is not installed (command not found), please :ref:`faq_install_python`.

  1. Install a platformio and related packages:
pip install -U platformio

If your computer does not recognize pip command, try to install it first using these instructions.

For upgrading platformio to the latest version:

pip install -U platformio

Or:

pio upgrade

Virtual Environment

PlatformIO Core may be installed into isolated Python environment. This method is very good if you don't want to install PlatformIO Core Python's dependencies (packages) into your global system scope. :ref:`pioide` uses this method to install PlatformIO Core.

Default and recommended environment folder is ":ref:`projectconf_pio_core_dir`/penv". You can print environment folder path using the next command in your system terminal:

python -c "import os; print(os.path.join(os.getenv('PLATFORMIO_CORE_DIR', os.path.join(os.path.expanduser('~'), '.platformio')), 'penv'))"

######################## Examples
# Windows
# C:\Users\UserName\.platformio\penv

# Linux
# ~/.platformio/penv
# /home/username/.platformio/penv

# macOS
# ~/.platformio/penv
# /Users/username/.platformio/penv

Prerequisites

  1. Please remove existing PlatformIO Core environment folder if exists. See above command how to get path to environment folder.

  2. Please check that you have a valid Python interpreter running a next command in system terminal. Python 2.7.9+ or Python 3.5+ is recommended.

    python --version

# or, for Unix (Linux, Mac), you can use `python2` or `python3` aliases
python2 --version
python3 --version

    Warning

    Windows Users: If you already tried to install :ref:`pioide` and did not get success, please open system's Control Panel > Installed Programs, and check if PlatformIO IDE tried to install an own isolated Python 2.7 version. Please uninstall it. Also is good to uninstall all Python interpreters from a system and install manually the latest Python using :ref:`faq_install_python` guide.

  3. Make sure virtualenv --help command exists in a system, otherwise, please install it manually using pip install virtualenv or pip2 install virtualenv command.

    If pip (Python Package Manager) does not exists, you have to install it manually. See https://pip.pypa.io/en/stable/installing/

Creating

  1. Create a folder which contains all the necessary executables to use the packages that PIO Core would need using virtualenv command:

    virtualenv /path/to/.platformio/penv

# If you want to use a custom Python interpreter
virtualenv --python=/path/to/custom/python /path/to/.platformio/penv

# EXAMPLES
# Windows
virtualenv C:\Users\UserName\.platformio\penv
virtualenv --python=C:\Python27\python.exe  C:\Users\UserName\.platformio\penv

# Unix (Linux, Mac)
virtualenv ~/.platformio/penv
virtualenv -p python3 ~/.platformio/penv

  2. Activate virtual environment

    # Windows
C:\Users\UserName\.platformio\penv

# Unix (Linux, Mac)
source /path/to/.platformio/penv/bin/activate
# or
. /path/to/.platformio/penv/bin/activate

  3. Install PIO Core into virtual environment

    pip install -U platformio

If you plan to use PIO Core commands outside virtual environment, please :ref:`piocore_install_shell_commands`.

Development Version

Warning

If you use :ref:`pioide`, please enable development version:

Install the latest PlatformIO from the develop branch:

# uninstall existing version
pip uninstall platformio

# install the latest development version of PlatformIO
pip install -U https://github.com/platformio/platformio-core/archive/develop.zip

If you want to be up-to-date with the latest develop version of PlatformIO, then you need to re-install PlatformIO each time you see a new commits in PlatformIO GitHub repository (branch: develop) like so:

pip install -U https://github.com/platformio/platformio-core/archive/develop.zip

Or:

pio upgrade --dev

To revert to the latest stable version:

pip uninstall platformio
pip install -U platformio

Install Shell Commands

:ref:`piocore` consists of 2 standalone tools in a system:

If you have :ref:`pioide` already installed, you do not need to install :ref:`piocore` separately. Just link these tools with your shell:

Unix and Unix-like

In Unix and Unix-like systems, there are multiple ways to achieve this.

Method 1

You can export PlatformIO executables' directory to the PATH environmental variable. This method will allow you to execute platformio commands from any terminal emulator as long as you're logged in as the user PlatformIO is installed and configured for.

If you use Bash as your default shell, you can do it by editing either ~/.profile or ~/.bash_profile and adding the following line:

export PATH=$PATH:~/.platformio/penv/bin

If you use Zsh, you can either edit ~/.zprofile and add the code above, or for supporting both, Bash and Zsh, you can first edit ~/.profile and add the code above, then edit ~/.zprofile and add the following line:

emulate sh -c '. ~/.profile'

After everything's done, just restart your session (log out and log back in) and you're good to go.

If you don't know the difference between the two, check out this page.

Method 2

Go to the PlatformIO menu → Settings → PlatformIO IDE, scroll down to the Custom PATH for `platformio` command and enter the following: ~/.platformio/penv/bin. After you've done that, you'll need to go to the PlatformIO menu → Settings → PlatformIO IDE Terminal, scroll down to the Toggles section and uncheck the Login Shell checkbox. Finally, restart your editor/IDE and check out the result.

Method 3

You can create system-wide symlinks. This method is not recommended if you have multiple users on your computer because the symlinks will be broken for other users and they will get errors while executing PlatformIO commands. If that's not a problem, open your system terminal app and paste these commands (MAY require administrator access sudo):

ln -s ~/.platformio/penv/bin/platformio /usr/local/bin/platformio
ln -s ~/.platformio/penv/bin/pio /usr/local/bin/pio
ln -s ~/.platformio/penv/bin/piodebuggdb /usr/local/bin/piodebuggdb

After that, you should be able to run PlatformIO from terminal. No restart is required.

Windows

Please read one of these instructions How do I set or change the PATH system variable?

You need to edit system environment variable called Path and append C:\Users\UserName\.platformio\penv\Scripts; path in the beginning of a list (please replace UserName with your account name).

Uninstall PIO Core and dependent packages

  • Uninstall PIO Core tool

    # uninstall standalone PIO Core installed via `pip`
pip uninstall platformio

# uninstall Homebrew's PIO Core (only macOS users if you installed it via Homebrew before)
brew uninstall platformio

  • Dependent packages, global libraries are installed to :ref:`projectconf_pio_core_dir` folder (in user's HOME directory). Just remove it.

Troubleshooting

Note

Linux OS: Don't forget to install "udev" rules file 99-platformio-udev.rules (an instruction is located in the file).

Windows OS: Please check that you have correctly installed USB driver from board manufacturer

For further details, frequently questions, known issues, please refer to :ref:`faq`.