mirror of
https://github.com/platformio/platformio-core.git
synced 2025-07-30 01:57: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.
|
||||
|
||||
PlatformIO IDE Demo
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Soon.
|
||||
|
||||
PlatformIO CLI Demo
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Wiring Blink
|
||||
------------
|
||||
"Blink Project"
|
||||
---------------
|
||||
|
||||
.. image:: _static/platformio-demo-wiring.gif
|
||||
|
||||
|
||||
@ -78,6 +78,9 @@ Manual Installation
|
||||
|
||||
.. image:: ../_static/ide-atom-platformio-install.png
|
||||
|
||||
|
||||
.. _atom_ide_quickstart:
|
||||
|
||||
Quick Start
|
||||
-----------
|
||||
|
||||
|
||||
@ -11,69 +11,250 @@
|
||||
|
||||
.. _quickstart:
|
||||
|
||||
Quickstart
|
||||
==========
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
.. note::
|
||||
Please read `Get Started <http://platformio.org/#!/get-started>`_
|
||||
from the official WebSite.
|
||||
If you are looking for a Qucik Start for PlatformIO IDE please follow to
|
||||
: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>`_
|
||||
or via :ref:`cmd_boards` command.
|
||||
This tutorial is based on the next popular embedded boards and development
|
||||
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
|
||||
|
||||
$ 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.
|
||||
You can specify another project directory via
|
||||
`platformio init -d %PATH_TO_THE_PROJECT_DIR%` command.
|
||||
Platform: teensy
|
||||
---------------------------------------------------------------------------
|
||||
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 ***
|
||||
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)
|
||||
According to the table above the ID/TYPE for Teensy 3.1 is ``teensy31``. Also,
|
||||
the ID for Arduino UNO is ``uno`` and for NodeMCU 1.0 (ESP-12E Module)
|
||||
is ``nodemcuv2``.
|
||||
|
||||
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
|
||||
:ref:`Project Configuration File (platformio.ini) <projectconf>` and run:
|
||||
PlatformIO ecosystem contains huge database with pre-configured settings for the
|
||||
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
|
||||
|
||||
$ platformio run
|
||||
|
||||
# if you don't have specified `targets = upload` option for environment,
|
||||
# then you can upload firmware manually with this command:
|
||||
$ platformio run --target upload
|
||||
|
||||
# clean project
|
||||
$ platformio run --target clean
|
||||
project_dir
|
||||
├── lib
|
||||
│ └── readme.txt
|
||||
├── platformio.ini
|
||||
└── src
|
||||
└── main.cpp
|
||||
|
||||
|
||||
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>`_
|
||||
* :ref:`userguide` for PlatformIO commands
|
||||
* `Quickstart for Espressif ESP8266 <https://github.com/esp8266/Arduino/blob/master/doc/platformio.md>`_
|
||||
* :ref:`userguide` for PlatformIO CLI commands
|
||||
|
||||
Reference in New Issue
Block a user