diff --git a/docs/_static/ide/cloud9/ide-cloud9-demo.jpg b/docs/_static/ide/cloud9/ide-cloud9-demo.jpg new file mode 100644 index 00000000..248eb5a5 Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-demo.jpg differ diff --git a/docs/_static/ide/cloud9/ide-cloud9-init-project.png b/docs/_static/ide/cloud9/ide-cloud9-init-project.png new file mode 100644 index 00000000..1bb19045 Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-init-project.png differ diff --git a/docs/_static/ide/cloud9/ide-cloud9-install-pio-cli.png b/docs/_static/ide/cloud9/ide-cloud9-install-pio-cli.png new file mode 100644 index 00000000..8b061286 Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-install-pio-cli.png differ diff --git a/docs/_static/ide/cloud9/ide-cloud9-new-workspace.png b/docs/_static/ide/cloud9/ide-cloud9-new-workspace.png new file mode 100644 index 00000000..ebc7381c Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-new-workspace.png differ diff --git a/docs/_static/ide/cloud9/ide-cloud9-runner-ota-devices.png b/docs/_static/ide/cloud9/ide-cloud9-runner-ota-devices.png new file mode 100644 index 00000000..f581bb31 Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-runner-ota-devices.png differ diff --git a/docs/_static/ide/cloud9/ide-cloud9-runner-ota-serial-monitor.png b/docs/_static/ide/cloud9/ide-cloud9-runner-ota-serial-monitor.png new file mode 100644 index 00000000..17547a71 Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-runner-ota-serial-monitor.png differ diff --git a/docs/_static/ide/cloud9/ide-cloud9-runner-ota-uploading.png b/docs/_static/ide/cloud9/ide-cloud9-runner-ota-uploading.png new file mode 100644 index 00000000..cbbde699 Binary files /dev/null and b/docs/_static/ide/cloud9/ide-cloud9-runner-ota-uploading.png differ diff --git a/docs/ide/cloud9.rst b/docs/ide/cloud9.rst index c3f7535f..d7fc6370 100644 --- a/docs/ide/cloud9.rst +++ b/docs/ide/cloud9.rst @@ -22,7 +22,168 @@ server output, and Run apps easily with the built-in Terminal and Runners. .. contents:: +.. note:: + + 1. Please make sure to read :ref:`pio_remote` guide first. + 2. You need :ref:`cmd_account` if you don't have it. Registration is FREE. + 3. You should have a run :ref:`cmd_remote_agent` on a local host machine + where hardware devices are connected or visible for remote operations. + +Demo +---- + +.. image:: ../_static/ide/cloud9/ide-cloud9-demo.jpg + :target: https://www.youtube.com/watch?v=NX56_0Ea_K8 + Integration ----------- -@TODO \ No newline at end of file +1. `Sign in to Cloud9 `_. A registration is FREE + and gives you for FREE 1 private workspace (where you can host multiple + PlatformIO Projects) and unlimited public workspaces. + +2. Create a new workspace using **Blank** template + +.. image:: ../_static/ide/cloud9/ide-cloud9-new-workspace.png + +3. Install PlatformIO CLI using Cloud IDE Terminal. Paste a next command + +.. code-block:: bash + + sudo python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/develop/scripts/get-platformio.py)" + +.. image:: ../_static/ide/cloud9/ide-cloud9-install-pio-cli.png + +4. Log in to :ref:`cmd_account` using :ref:`cmd_account_login` command. + + +Quick Start +----------- + +Let's create our first PlatformIO-based Cloud9 Project + +1. Initialize new PlatformIO-based Project. Run a next command in Cloud IDE + Terminal: + +.. code-block:: bash + + platformio init --board + + # initialize project for Arduino Uno + platformio init --board uno + + To get board ``ID`` please use :ref:`cmd_boards` command or + `Embedded Boards Explorer `_. + +2. Create new source file named ``main.cpp`` in ``src`` folder using + Project Tree (left side). Please make right click on ``src`` folder, + then "New File" and insert a next content: + +.. code-block:: c + + #include + + int i = 0; + + void setup() { + Serial.begin(9600); + Serial.println("Hello Cloud9!"); + } + + void loop() { + /* serial echo */ + while (Serial.available()) { + Serial.write(Serial.read()); + } + + i++; + Serial.println(i); + delay(100); + } + +.. image:: ../_static/ide/cloud9/ide-cloud9-init-project.png + +3. If you prefer to work with PlatformIO CLI, then you can process project + using Cloud IDE Terminal and the next commands: + + * :ref:`cmd_run` - build project + * :ref:`pio run -t clean ` - clean project + * :ref:`pio remote run -t upload ` - upload firmware Over-The-Air + + If you are interested in better integration with Cloud9 and GUI, please + read guide below where we will explain how to create custom Build System + for PlatformIO and own Runners. + +PlatformIO Build System +----------------------- + +Cloud9 allows to create own build system and use hotkey or command +(Menu: Run > Build) to build a project. + +Let's create PlatformIO Build System that will be used for C/C++/H/INO/PDE +files by default. Please click on ``Menu: Run > Build System > New Build System`` +and replace all content with the next: + +.. code-block:: js + + { + "cmd" : ["pio", "run", "-d", "$file"], + "info" : "Building $project_path/$file_name", + "selector": "^.*\\.(cpp|c|h|hpp|S|ini|ino|pde)$" + } + +Save new Build System and give a name ``PIOBuilder``. Now, you can select it +as default Build System using ``Menu: Run > Build System > PIOBuilder``. + +OTA Device Manager +------------------ + +Over-The-Air (OTA) Device Manager works in pair with :ref:`pio_remote`. +You can list remote devices that are connected to host machine where +:ref:`pio_remote_agent` is started or are visible for it. +To list active agents please use this command :ref:`cmd_remote_agent_list`. + +Let's create New Run Configuration (shortcut) that will be used for OTA Manager. +Please click on ``Menu: Run > Run Configurations > Manage...``, then +"Add New Config" and specify the next values: + +* **First Blank Input**: a name of runner. Please set it to "PIO: Remote Devices" +* **Command**: set to ``pio remote device list`` +* **Runner**: set to "Shell command" + +.. image:: ../_static/ide/cloud9/ide-cloud9-runner-ota-devices.png + +OTA Firmware Uploading +---------------------- + +Over-The-Air (OTA) Firmware Uploading works in pair with :ref:`pio_remote`. +You can deploy firmware to any devices which are visible for :ref:`pio_remote_agent`. +To list active agents please use this command :ref:`cmd_remote_agent_list`. + +Let's create New Run Configuration (shortcut) that will be used for OTA Uploads. +Please click on ``Menu: Run > Run Configurations > Manage...``, then +"Add New Config" and specify the next values: + +* **First Blank Input**: a name of runner. Please set it to "PIO: Remote Upload" +* **Command**: set to ``pio remote run -t upload`` +* **Runner**: set to "Shell command" + +.. image:: ../_static/ide/cloud9/ide-cloud9-runner-ota-uploading.png + +OTA Serial Port Monitor +----------------------- + +Over-The-Air (OTA) Serial Port Monitor works in pair with :ref:`pio_remote`. +You can read or send data to any device that is connected to host machine +where :ref:`pio_remote_agent` is started. +To list active agents please use this command :ref:`cmd_remote_agent_list`. + +Let's create New Run Configuration (shortcut) that will be used for OTA Serial Port Monitor. +Please click on ``Menu: Run > Run Configurations > Manage...``, then +"Add New Config" and specify the next values: + +* **First Blank Input**: a name of runner. Please set it to "PIO: Remote Serial Monitor" +* **Command**: set to ``pio remote device monitor`` +* **Runner**: set to "Shell command" + +.. image:: ../_static/ide/cloud9/ide-cloud9-runner-ota-serial-monitor.png diff --git a/docs/userguide/remote/cmd_agent.rst b/docs/userguide/remote/cmd_agent.rst index f6ff1d7b..33e350f1 100644 --- a/docs/userguide/remote/cmd_agent.rst +++ b/docs/userguide/remote/cmd_agent.rst @@ -25,6 +25,8 @@ network operations Over-The-Air. .. contents:: +.. _cmd_remote_agent_list: + platformio remote agent list ----------------------------