mirror of
https://github.com/platformio/platformio-core.git
synced 2025-07-31 02:27:13 +02:00
Refactor Quick Start page
This commit is contained in:
Ivan Kravets
@ -21,16 +21,8 @@ Project Examples
|
|||||||
|
|
||||||
Preconfigured demo projects are located in `PlatformIO GitHub <https://github.com/platformio/platformio/tree/develop/examples>`_ repository.
|
Preconfigured demo projects are located in `PlatformIO GitHub <https://github.com/platformio/platformio/tree/develop/examples>`_ repository.
|
||||||
|
|
||||||
PlatformIO IDE Demo
|
"Blink Project"
|
||||||
^^^^^^^^^^^^^^^^^^^
|
---------------
|
||||||
|
|
||||||
Soon.
|
|
||||||
|
|
||||||
PlatformIO CLI Demo
|
|
||||||
^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Wiring Blink
|
|
||||||
------------
|
|
||||||
|
|
||||||
.. image:: _static/platformio-demo-wiring.gif
|
.. image:: _static/platformio-demo-wiring.gif
|
||||||
|
|
||||||
|
|||||||
@ -78,6 +78,9 @@ Manual Installation
|
|||||||
|
|
||||||
.. image:: ../_static/ide-atom-platformio-install.png
|
.. image:: ../_static/ide-atom-platformio-install.png
|
||||||
|
|
||||||
|
|
||||||
|
.. _atom_ide_quickstart:
|
||||||
|
|
||||||
Quick Start
|
Quick Start
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
|
|||||||
@ -11,69 +11,250 @@
|
|||||||
|
|
||||||
.. _quickstart:
|
.. _quickstart:
|
||||||
|
|
||||||
Quickstart
|
Quick Start
|
||||||
==========
|
===========
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
Please read `Get Started <http://platformio.org/#!/get-started>`_
|
If you are looking for a Qucik Start for PlatformIO IDE please follow to
|
||||||
from the official WebSite.
|
:ref:`PlatformIO IDE Quick Start <atom_ide_quickstart>` page.
|
||||||
|
|
||||||
PlatformIO IDE
|
This tutorial introduces you to the basics of PlatformIO Command Line Interface
|
||||||
--------------
|
(CLI) workflow and shows you a creation process of a simple cross-platform
|
||||||
|
“Blink” Project. After finishing you will have a general understanding of how
|
||||||
|
to work with the multiple development platforms and embedded boards.
|
||||||
|
|
||||||
Please follow to the Quickstart section of :ref:`ide_atom`.
|
Setting Up the Project
|
||||||
|
----------------------
|
||||||
|
|
||||||
PlatformIO CLI
|
PlatformIO CLI provides special :ref:`cmd_init` command for configuring your projects.
|
||||||
--------------
|
It allows to initialize new empty project or update existing with the new data.
|
||||||
|
|
||||||
1. :ref:`installation`.
|
What is more, :ref:`cmd_init` can be used for :ref:`ide`. It means that you will
|
||||||
|
be able to import pre-generated PlatformIO project using favourite IDE and
|
||||||
|
extend it with the professional instruments for IoT development.
|
||||||
|
|
||||||
2. Find board ``type`` using `Embedded Boards Explorer <http://platformio.org/#!/boards>`_
|
This tutorial is based on the next popular embedded boards and development
|
||||||
or via :ref:`cmd_boards` command.
|
platforms using *Arduino Wiring-based Framework*:
|
||||||
|
|
||||||
3. Initialize new PlatformIO based project via :ref:`cmd_init` command with the
|
|
||||||
pre-configured environments for your boards:
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Platform
|
||||||
|
- Board
|
||||||
|
- Framework
|
||||||
|
|
||||||
|
* - Atmel AVR
|
||||||
|
- Arduino Uno (8-bit ATmega328P)
|
||||||
|
- Arduino Wiring-based Framework
|
||||||
|
|
||||||
|
* - Espressif
|
||||||
|
- NodeMCU 1.0 (32-bit ESP8266)
|
||||||
|
- Arduino Wiring-based Framework
|
||||||
|
|
||||||
|
* - Teensy
|
||||||
|
- Teensy 3.1 (32-bit ARM MK20DX256)
|
||||||
|
- Arduino Wiring-based Framework
|
||||||
|
|
||||||
|
Board Identifier
|
||||||
|
----------------
|
||||||
|
|
||||||
|
:ref:`cmd_init` command requires to specify board identifier (ID/TYPE). It can
|
||||||
|
be found using `Embedded Boards Explorer <http://platformio.org/#!/boards>`_
|
||||||
|
or :ref:`cmd_boards` command. For example, using :ref:`cmd_boards` let's try
|
||||||
|
to find Teensy boards:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
$ platformio init --board=TYPE_1 --board=TYPE_2 --board=TYPE_N
|
> platformio boards teensy
|
||||||
|
|
||||||
The current working directory *** will be used for the new project.
|
Platform: teensy
|
||||||
You can specify another project directory via
|
---------------------------------------------------------------------------
|
||||||
`platformio init -d %PATH_TO_THE_PROJECT_DIR%` command.
|
Type MCU Frequency Flash RAM Name
|
||||||
|
---------------------------------------------------------------------------
|
||||||
|
teensy20 atmega32u4 16Mhz 31kB 2.5kB Teensy 2.0
|
||||||
|
teensy30 mk20dx128 48Mhz 128kB 16kB Teensy 3.0
|
||||||
|
teensy31 mk20dx256 72Mhz 256kB 64kB Teensy 3.1 / 3.2
|
||||||
|
teensylc mkl26z64 48Mhz 62kB 8kB Teensy LC
|
||||||
|
teensy20pp at90usb1286 16Mhz 127kB 8kB Teensy++ 2.0
|
||||||
|
|
||||||
The next files/directories will be created in ***
|
According to the table above the ID/TYPE for Teensy 3.1 is ``teensy31``. Also,
|
||||||
platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
|
the ID for Arduino UNO is ``uno`` and for NodeMCU 1.0 (ESP-12E Module)
|
||||||
src - Put your source files here
|
is ``nodemcuv2``.
|
||||||
lib - Put here project specific (private) libraries
|
|
||||||
Do you want to continue? [y/N]: y
|
|
||||||
Project has been successfully initialized!
|
|
||||||
Useful commands:
|
|
||||||
`platformio run` - process/build project from the current directory
|
|
||||||
`platformio run --target upload` or `platformio run -t upload` - upload firmware to embedded board
|
|
||||||
`platformio run --target clean` - clean project (remove compiled files)
|
|
||||||
|
|
||||||
Put your source files ``*.h, *.c, *.cpp or *.ino`` to ``src`` directory.
|
|
||||||
|
|
||||||
4. Process the project's environments.
|
Initialize Project
|
||||||
|
------------------
|
||||||
|
|
||||||
Change working directory to the project's root where is located
|
PlatformIO ecosystem contains huge database with pre-configured settings for the
|
||||||
:ref:`Project Configuration File (platformio.ini) <projectconf>` and run:
|
most popular embedded boards. It helps you to forget about installing
|
||||||
|
toolchains, writing build scripts or configuring uploading process. Just tell
|
||||||
|
PlatformIO the Board ID and you will receive full working project with
|
||||||
|
pre-installed instruments for the professional development.
|
||||||
|
|
||||||
|
1. Create empty folder where you are going to initialize new PlatformIO
|
||||||
|
project. Then open system Terminal and change directory to it:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
# create new direcotry
|
||||||
|
> mkdir path_to_the_new_directory
|
||||||
|
|
||||||
|
# go to it
|
||||||
|
> cd path_to_the_new_directory
|
||||||
|
|
||||||
|
2. Initialize project for the boards mentioned above (you can specify more
|
||||||
|
than one board at time):
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
> platformio init --board uno --board nodemcuv2 --board teensy31
|
||||||
|
|
||||||
|
The current working directory *** will be used for the new project.
|
||||||
|
You can specify another project directory via
|
||||||
|
`platformio init -d %PATH_TO_THE_PROJECT_DIR%` command.
|
||||||
|
|
||||||
|
The next files/directories will be created in ***
|
||||||
|
platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
|
||||||
|
src - Put your source files here
|
||||||
|
lib - Put here project specific (private) libraries
|
||||||
|
Do you want to continue? [y/N]: y
|
||||||
|
Project has been successfully initialized!
|
||||||
|
Useful commands:
|
||||||
|
`platformio run` - process/build project from the current directory
|
||||||
|
`platformio run --target upload` or `platformio run -t upload` - upload firmware to embedded board
|
||||||
|
`platformio run --target clean` - clean project (remove compiled files)
|
||||||
|
|
||||||
|
|
||||||
|
Congrats! You have just created the first PlatformIO based Project with the
|
||||||
|
next structure:
|
||||||
|
|
||||||
|
* :ref:`projectconf`
|
||||||
|
* ``src`` directory where you should place source code
|
||||||
|
(``*.h, *.c, *.cpp, *.S, *.ino, etc.``)
|
||||||
|
* ``lib`` directory can be used for the project specific (private) libraries.
|
||||||
|
More details are located in ``lib/readme.txt`` file.
|
||||||
|
* Miscellaneous files for CVS and :ref:`ci` support.
|
||||||
|
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
If you need to add new board to the existing project please use
|
||||||
|
:ref:`cmd_init` again.
|
||||||
|
|
||||||
|
|
||||||
|
The result of just generated ``platformio.ini``:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
#
|
||||||
|
# Project Configuration File
|
||||||
|
#
|
||||||
|
# A detailed documentation with the EXAMPLES is located here:
|
||||||
|
# http://docs.platformio.org/en/latest/projectconf.html
|
||||||
|
#
|
||||||
|
|
||||||
|
# A sign `#` at the beginning of the line indicates a comment
|
||||||
|
# Comment lines are ignored.
|
||||||
|
|
||||||
|
# Simple and base environment
|
||||||
|
# [env:mybaseenv]
|
||||||
|
# platform = %INSTALLED_PLATFORM_NAME_HERE%
|
||||||
|
# framework =
|
||||||
|
# board =
|
||||||
|
#
|
||||||
|
# Automatic targets - enable auto-uploading
|
||||||
|
# targets = upload
|
||||||
|
|
||||||
|
[env:uno]
|
||||||
|
platform = atmelavr
|
||||||
|
framework = arduino
|
||||||
|
board = uno
|
||||||
|
|
||||||
|
[env:nodemcuv2]
|
||||||
|
platform = espressif
|
||||||
|
framework = arduino
|
||||||
|
board = nodemcuv2
|
||||||
|
|
||||||
|
[env:teensy31]
|
||||||
|
platform = teensy
|
||||||
|
framework = arduino
|
||||||
|
board = teensy31
|
||||||
|
|
||||||
|
|
||||||
|
Now, we need to create ``main.cpp`` file and place it to ``src`` folder of our
|
||||||
|
newly created project. The contents of ``src/main.cpp``:
|
||||||
|
|
||||||
|
.. code-block:: cpp
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Blink
|
||||||
|
*
|
||||||
|
* Turns on an LED on for one second,
|
||||||
|
* then off for one second, repeatedly.
|
||||||
|
*/
|
||||||
|
#include "Arduino.h"
|
||||||
|
|
||||||
|
void setup()
|
||||||
|
{
|
||||||
|
// initialize LED digital pin as an output.
|
||||||
|
pinMode(LED_BUILTIN, OUTPUT);
|
||||||
|
}
|
||||||
|
|
||||||
|
void loop()
|
||||||
|
{
|
||||||
|
// turn the LED on (HIGH is the voltage level)
|
||||||
|
digitalWrite(LED_BUILTIN, HIGH);
|
||||||
|
|
||||||
|
// wait for a second
|
||||||
|
delay(1000);
|
||||||
|
|
||||||
|
// turn the LED off by making the voltage LOW
|
||||||
|
digitalWrite(LED_BUILTIN, LOW);
|
||||||
|
|
||||||
|
// wait for a second
|
||||||
|
delay(1000);
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
The final Project structure:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
$ platformio run
|
project_dir
|
||||||
|
├── lib
|
||||||
# if you don't have specified `targets = upload` option for environment,
|
│ └── readme.txt
|
||||||
# then you can upload firmware manually with this command:
|
├── platformio.ini
|
||||||
$ platformio run --target upload
|
└── src
|
||||||
|
└── main.cpp
|
||||||
# clean project
|
|
||||||
$ platformio run --target clean
|
|
||||||
|
|
||||||
|
|
||||||
Useful links:
|
Process Project
|
||||||
|
---------------
|
||||||
|
|
||||||
|
PlatformIO CLI provides special :ref:`cmd_run` command to process project. If
|
||||||
|
you call it without any arguments, PlatformIO Build System will process all
|
||||||
|
project environments (which were created per each board specified above). Here
|
||||||
|
are a few useful commands:
|
||||||
|
|
||||||
|
* ``platformio run``. Process (build) all environments specified in
|
||||||
|
:ref:`projectconf`
|
||||||
|
* ``platformio run --target upload``. Build project and upload firmware to the
|
||||||
|
all devices specified in :ref:`projectconf`
|
||||||
|
* ``platformio run --target clean``. Clean project (delete compiled objects)
|
||||||
|
* ``platformio run -e uno``. Process only ``uno`` environment
|
||||||
|
* ``platformio run -e uno -t upload``. Build project only for ``uno`` and upload
|
||||||
|
firmware.
|
||||||
|
|
||||||
|
Please follow to :option:`platformio run --target` documentation for the other
|
||||||
|
targets.
|
||||||
|
|
||||||
|
Finally, demo which demonstrates building project and uploading firmware to
|
||||||
|
Arduino Uno:
|
||||||
|
|
||||||
|
.. image:: _static/platformio-demo-wiring.gif
|
||||||
|
|
||||||
|
Further Reading
|
||||||
|
---------------
|
||||||
|
|
||||||
* `Project examples <https://github.com/platformio/platformio/tree/develop/examples>`_
|
* `Project examples <https://github.com/platformio/platformio/tree/develop/examples>`_
|
||||||
* :ref:`userguide` for PlatformIO commands
|
* :ref:`userguide` for PlatformIO CLI commands
|
||||||
* `Quickstart for Espressif ESP8266 <https://github.com/esp8266/Arduino/blob/master/doc/platformio.md>`_
|
|
||||||
|
|||||||
Reference in New Issue
Block a user