ESP8266 Support WIKI

User Tools

Site Tools


toolchain

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
toolchain [2015/09/22 11:56]
terrye [How to set a VM to host your toolchain] add expat
toolchain [2018/01/06 18:53]
fabix [How to setup a VM to host your toolchain]
Line 1: Line 1:
 ====== How to set up manually the GCC toolchain and SDK ====== ====== How to set up manually the GCC toolchain and SDK ======
  
-An opensource toolchain is available in https://​github.com/​pfalcon/​esp-open-sdk. It is ready to run on Linux hosts only.  If you don't use a Linux development machine, then the easiest way to build and to use the toolchain is to set up a Linux Virtual Machine (VM) on your development machine, as described in the [[toolchain#​How to set a VM to host your toolchain|following section]]. ​ Another alternative is to use a low cost Linux board such as a [[https://​www.raspberrypi.org/​products/​model-b-plus/|Respberry PI2]].  Once you have your working Linux environment,​ setting up the toolchain is easy.  ​+An opensource toolchain is available in https://​github.com/​pfalcon/​esp-open-sdk. It is ready to run on Linux hosts only.  If you don't use a Linux development machine, then the easiest way to build and to use the toolchain is to set up a Linux Virtual Machine (VM) on your development machine, as described in the [[toolchain#​How to set a VM to host your toolchain|following section]]. ​ Another alternative is to use a low cost Linux board such as a [[https://​www.raspberrypi.org/​products/​raspberry-pi-2-model-b/|Raspberry Pi 2]].  Once you have your working Linux environment,​ setting up the toolchain is easy.  ​
  
   * Use Git command to clone the git repository **esp-open-sdk** into your local directory:   * Use Git command to clone the git repository **esp-open-sdk** into your local directory:
Line 21: Line 21:
     alias xgcc="​xtensa-lx106-elf-gcc"​     alias xgcc="​xtensa-lx106-elf-gcc"​
  
-====== How to set a VM to host your toolchain ​======+===== How to setup a VM to host your toolchain =====
  
-If you run Windows, OSX or Linux 64bit, then one of the easiest ways of setting up a development is to use a [[wp>​virtualization|virtualization]] product to run a dedicated toolchain VM.  There are a number of products available, but my personal preference is [[https://​www.virtualbox.org/​|Oracle'​s VirtualBox]] as this is free, flexible and performs well on most common Intel / AMD platforms. This brief overview is written assuming the use of VirtalBox, but largely applies to setting up VM on most platforms.+If you run Windows, OSX or Linux 64bit, then one of the easiest ways of setting up a development is to use a [[wp>​virtualization|virtualization]] product to run a dedicated toolchain VM.  There are a number of products available, but my personal preference is [[https://​www.virtualbox.org/​|Oracle'​s VirtualBox]] as this is free, flexible and performs well on most common Intel / AMD platforms. This brief overview is written assuming the use of VirtualBox, but largely applies to setting up VM on most platforms.
  
-  * Since nearly all toolchain work is done at the command prompt, it is simpler to configure your VM as a server ​instance ​and access it over SSH using the ''​ssh''​ command on Linux or OSX and a product such as puTTY on Windows. If you decided to go this route then you don't need to learn the a Linux windows environment since you can access and manipulate both files and console sessions through your familiar Windows environment.+  * Since nearly all toolchain work is done at the command prompt, it is simpler to configure your VM as a server and access it over SSH using the ''​ssh''​ command on Linux or OSX and a product such as puTTY on Windows. If you decided to go this route then you don't need to learn the a Linux windows environment since you can access and manipulate both files and console sessions through your familiar Windows environment.
  
-  * A simple VM with 384-512Mb ​RAM and 8Gb disk is easily sufficient to develop and build EESP8266 SDK-based images+  * A simple VM with 384Mb RAM and 8Gb disk is easily sufficient to develop and build EESP8266 SDK-based images, and to keep thing simple I suggest using minimal ​simple ​64bit Ubuntu server configuration ​which mirrors the one that the nodemcu project uses to test its builds.
- +
-  * To keep thing simple I suggest using simple ​32bit Ubuntu server configuration.+
  
   * The first thing that you need to do is to download the VM product. ​ In the case of VirtualBox, you don't need any of Oracle'​s closed source layered extension packs, so you can do a ''​sudo apt-get install virtualbox''​ on Debian and derived Linux systems such as Ubuntu. ​ In the case of Windows and OSX, follow the instructions on the product'​s [[https://​www.virtualbox.org/​wiki/​Downloads|Downloads]] page or follow one of the many step-by-step guides on Youtube and elsewhere.   * The first thing that you need to do is to download the VM product. ​ In the case of VirtualBox, you don't need any of Oracle'​s closed source layered extension packs, so you can do a ''​sudo apt-get install virtualbox''​ on Debian and derived Linux systems such as Ubuntu. ​ In the case of Windows and OSX, follow the instructions on the product'​s [[https://​www.virtualbox.org/​wiki/​Downloads|Downloads]] page or follow one of the many step-by-step guides on Youtube and elsewhere.
  
-  * You now need to download the Ubuntu Minimal installation CD for [[http://​archive.ubuntu.com/​ubuntu/​dists/​trusty/​main/​installer-amd64/​current/​images/​netboot/​mini.iso|Ubuntu ​14.04 LTS]] (less than 40Mb). +  * You now need to download the Ubuntu Minimal installation CD for [[http://​archive.ubuntu.com/​ubuntu/​dists/​precise-updates/​main/​installer-amd64/​current/​images/​netboot/​mini.iso|Ubuntu ​12.04 LTS Amd64 mini.iso]](This is less than 30Mb).  NodeMCU uses the [[https://​travis-ci.com/​|Travis-CI]] system to validate the build integrity of any changes to its Github repostiory; Travis also uses Ubuntu 12.04 VMs, so NodeMNCU contains a pre-built toolchain for this VM configuration in its ''​tools''​ folder and unpacking this toolchain is a lot simpler and takes up about 2½Gb less disk space than building it yourself.
  
-  * VirtualBox has both a complete GUI and commandline interface but again the simplest thing to do is to use the GUI and follow one of the tutorials to create a new virtual machine (which I will call''​nodeMCU'',​ but you are free to choose whatever name your wish) (the bold options are non-default):​  +  * VirtualBox has both a complete GUI and commandline interfacebut again the simplest thing to do is to use the VirtualBox ​GUI and follow one of the tutorials to create a new virtual machine (which I will call ''​nodemcu'',​ but you are free to choose whatever name your wish) (the bold options are non-default):​  
-    * **32-bit Ubuntu; 384Mb RAM** +    * **64-bit Ubuntu; 384Mb RAM**. 
-    * 1 CPU; enable H/W virtualization assist if available +    * 1 CPU; **PAE disabled**; and enable H/W virtualization assist if available. 
-    * set minimal video memory (**4Mb** and no fancy features) +    * Set a minimal video memory (**4Mb** and no fancy features). 
-    * enable ​a IDE CD/DVD and map the **''​mini.iso''​** to this. +    * Enable ​a IDE CD/DVD and map the **''​mini.iso''​** to this. 
-    * enable ​and create a VDI-based dynamically allocated 8Gb SATA HDD. (You might want to place the VDI file in a specific work folder rather leaving it hidden in the VirtualBox folder hierarchy.) +    * Enable ​and create a VDI-based dynamically allocated 8Gb SATA HDD. (You might want to place the VDI file in a specific work folder rather leaving it hidden in the VirtualBox folder hierarchy.) 
-    * add one NAT-based network adapter. ​  +    * You will need one NAT-based network adapter.  
-    * You don't need any other virtual hardware or features, many some find the sheared ​folders feature worth installing. ​ I don't bother nowadays and just use ''​rsync''​ / ''​scp''​ / ''​sftp''​.+    * You don't need any other virtual hardware or features, many some find the shared ​folders feature worth installing. ​ I don't bother nowadays and just use ''​rsync''​ / ''​scp''​ / ''​sftp''​.
  
-  * NAT is described in the VirtualBox documentation,​ but in essence the VM host application acts as a router, so the VM doesn'​t have its own IP address. ​ Instead you map host IP ports to client posts through the **Network -> Advanced -> Port Forwarding** function and a common port is to forward ''​127.0.0.1:​2222''​ to ''​10.0.2.15:​22''​ so that doing an SSH to ''​localhost:​2222''​ connects to the VM's default SSH port. Host and off machine process can only access the VM through a mapped port when the VM is running. ​ (You will need to do an ''​ifconfig''​ after you've built the machine to validate the guest'​s actual IP address.) ​ //Note that if you have multiple VMs, then you should use a unique port for each SSH eg. 2222 for VM1; 2322 for VM2, etc.// ​ This just stops you shooting yourself in the foot.  ​+  * NAT is described in the VirtualBox documentation,​ but in essence the VM host application acts as a router, so the VM doesn'​t have its own IP address. ​ Instead you map host IP ports to client posts through the **Network -> Advanced -> Port Forwarding** function and a common port is to forward ​**''​127.0.0.1:​2222''​** to **''​10.0.2.15:​22''​** so that doing an SSH to ''​localhost:​2222''​ connects to the VM's default SSH port. Host and off-machine process can only access the VM through a mapped port when the VM is running. ​ (You will need to do an ''​ifconfig''​ after you've built the machine to validate the guest'​s actual IP address.) ​ //Note that if you have multiple VMs, then you should use a unique port for each SSH eg. 2222 for VM1; 2322 for VM2, etc.// ​ This stops you shooting yourself in the foot.  ​
  
-  *  You now start VM through the GUI and you will boot into the Ubuntu minimal install. There are again various YouTube and other tutorials which will take you through this (e.g. [[https://​www.youtube.com/​watch?​v=QBYrSUHPiX4|Ubuntu Server 14.04 LTS Network Installation Guide ]]), but what you need to do is to build a minimal server system that you can log onto over SSH. +  *  You now start VM through the GUI and you will boot into the Ubuntu minimal install. There are again various YouTube and other tutorials which will take you through this, but what you need to do is to build a minimal server system that you can log onto over SSH. 
-     * Use the arrow / tab /enter keys to select **Install** +     * Use the arrow / tab /enter keys to select **Install**. 
-     * Choose your language +     * Choose your language. 
-     * Chose your keyboard. ​ Don't use automatic; just do a manual selection+     * Chose your keyboard. ​ Don't use automatic; just do a manual selection.
      * Detect network and disable USB storage as you won't need it.      * Detect network and disable USB storage as you won't need it.
      * Give it the same host name as your VM machine name to keep things simple.      * Give it the same host name as your VM machine name to keep things simple.
      * Choose a local Ubuntu mirror, and step through the menus until you get to ''​Download Installer Components''​ and **continue** as you don't need any of these. ​ The installer occasionally goes silent for 30-60secs, but then downloads all of the core components over network from the mirror. ​ How long this takes depends on your internet bandwidth and how heavily the mirror is being hit, but 10-15 mins is typical. ​ Time for a coffee 8-)      * Choose a local Ubuntu mirror, and step through the menus until you get to ''​Download Installer Components''​ and **continue** as you don't need any of these. ​ The installer occasionally goes silent for 30-60secs, but then downloads all of the core components over network from the mirror. ​ How long this takes depends on your internet bandwidth and how heavily the mirror is being hit, but 10-15 mins is typical. ​ Time for a coffee 8-)
-     * Now let the menu step you through the inputs.  ​Nearly ​always ​the defaults ​apply. ​ You need to choose a user name.  Keep it the same as you use on your host.  //​Don'​t bother encrypting your home directory//​. ​ Use NTP to set the time. +     * Now let the menu step you through the inputs.  ​The defaults nearly ​always apply. ​ You need to choose a user name and password.  Keep the name the same as you use on your host.  //​Don'​t bother encrypting your home directory// ​and choose a simple password (as you will only use it 5 mins).  Use NTP to set the time. 
-     * Keep the disk partitioning simple: select **guided** / **use whole disk** / **All files in One Partition** and install the base system. ​ Another coffee or whatever, as this will chug along for another 20-60 mins.  Sorry guys, but this is a **//LOT//** less than Windows 10 LOL +     * Keep the disk partitioning simple: select **guided** / **use whole disk** / **All files in One Partition** and install the base system. ​ Another coffee or whatever, as this will chug along for another 20 mins or so.  Sorry guys, but this is a **//LOT//** less than Windows 10 LOL 
-     * When it comes to configuring the package manager, I untick everything and then select **no automatic updates**, for reasons given below,+     * When it comes to configuring the package manager, I untick everythingand then select **no automatic updates**, for reasons given below,
      * Only check **Basic Ubuntu Server** and **openSSH Server** on the Software Selection menu and hit continue to finish the install. ​ You are then prompted to remove the media which you do virtually through a VirtualBox menu option, and the installer then reboots the machine.      * Only check **Basic Ubuntu Server** and **openSSH Server** on the Software Selection menu and hit continue to finish the install. ​ You are then prompted to remove the media which you do virtually through a VirtualBox menu option, and the installer then reboots the machine.
      * At this point you can ''​sudo ipconfig''​ to check the IP details and ''​sudo poweroff''​ to shutdown the machine.      * At this point you can ''​sudo ipconfig''​ to check the IP details and ''​sudo poweroff''​ to shutdown the machine.
      * The basic server build is now complete.      * The basic server build is now complete.
  
-  * I suggest that you run the server from now on in what is called headless mode -- that is you start and stop the VM from a command line using ''​vboxmanage''​ commands and just like a real server, you will only want to have the server console available for exceptions ​system maintenance. ​ I use a set of aliases in my ''​.bashrc''​ on my laptop (Windows users can use ''​doskey''​ macros to achieve the same effect):+  * I suggest that you run the server from now on in what is called headless mode -- that is you start and stop the VM from a command line using ''​vboxmanage''​ commands and just like a real server, you will only need to have the server console available for exceptional ​system maintenance. ​(I never bother with it and do everything over SSH.)  I use a set of aliases in my ''​.bashrc''​ on my laptop(Windows users can use ''​doskey''​ macros to achieve the same effect.(Replace ''​nodemcu''​ by whatever you've called your VM.
  
-  ​alias nodemcustart='​vboxmanage startvm nodemcu --type headless'​ +``` 
-  alias nodemcusave='​vboxmanage controlvm nodemcu savestate'​ +    ​alias nodemcustart='​vboxmanage startvm nodemcu --type headless'​ 
-  alias nodemcu='​ssh -p 2222 localhost'​+    alias nodemcusave='​vboxmanage controlvm nodemcu savestate'​ 
 +    alias nodemcu='​ssh -p 2222 localhost'​ 
 +```
  
-  * A major advantage of the network install is that the latest versions of all packages at the point of the build are loaded into the system, so there'​s no need to do the 100s of patch updates that you typically need to do with Windows.  ​I am also going to lock the system down so that the only access to the system will be from your account on the host PC or laptop ​and that in effect no ports are exposed to the wider network. ​ The only way that the VM can be security compromised is if the host account and PC have been compromised so there is no point in adding extra tiers of security within the VM.+  * A major advantage of the network install is that the latest versions of all packages at the point of the build are loaded into the system, so there'​s no need to do the 100s of patch updates that you typically need to do with Windows.  ​We are going to lock the system down so that the only access to the system will be from your account on the host PC or laptop;  ​in effectno ports are exposed to the wider network. ​ The only way that the VM can be security compromised is if the host PC and host account ​have been compromised so there is no point in adding extra tiers of security within the VM.
  
-  * Start the server and log on using your username / password combination. (If using SSH or puTTY for the first time google "​**putty ​ using ssh keys authorize_keys**" and read up on how public key based SSH access works and is configured). ​ Now copy your public key to ''​~/​.ssh/​authorized_keys'' ​and ''​chown ​600 ~/​.ssh/​authorized_keys''​. You should now be able to log off and log on from your host without needing to enter a password.+  * Start the server and log on using your username / password combination. (If using SSH or puTTY for the first time google "​**putty ​ using ssh keys `authorized_keys`**" and read up on how public key based SSH access works and is configured). ​ Now copy your public key to `~/​.ssh/​authorized_keysand `chmod ​600 ~/​.ssh/​authorized_keys`. You should now be able to log off and log on from your host without needing to enter a password.
  
-  * Edit ''​/​etc/​ssh/​sshd_config'' ​and append the line ''​AllowUsers *@10.0.2.*'' ​to limit logon to access from the host PC. (You will neeed to use ''​sudo ​ nano''​ or ''​sudo vi''​ to do this). ​ And similarly do a ''​sudo visudo''​ to add ''​NOPASSWD''​ to the **''​%admin''​** and **''​%sudo''​** groups as follows; this enables you to access root privileges without having to enter a password (and log off and on again to check that these are working OK.)+  * Edit `/​etc/​ssh/​sshd_configand append the line `AllowUsers *@10.0.2.*to limit logon to access from the host PC. (You will neeed to use ''​sudo ​ nano''​ or ''​sudo vi''​ to do this). ​ And similarly do a ''​sudo visudo''​ to add ''​NOPASSWD''​ to the **''​%admin''​** and **''​%sudo''​** groups as follows; this enables you to access root privileges without having to enter a password (and log off and on again to check that these are working OK.) 
 + 
 +``` 
 +    %admin ALL=(ALL) NOPASSWD: ALL 
 +    %sudo  ALL=(ALL:​ALL) NOPASSWD: ALL 
 +```
  
-  %admin ALL=(ALL) NOPASSWD: ALL 
-  %sudo  ALL=(ALL:​ALL) NOPASSWD: ALL 
-  
   *  And lastly mangle your password so that only key-based access can work:   *  And lastly mangle your password so that only key-based access can work:
  
-  ​pwd=$(date|md5sum);​ echo -e "​$pwd\n$pwd"​|sudo passwd $USER +``` 
- +    ​pwd=$(date|md5sum);​ echo -e "​$pwd\n$pwd"​|sudo passwd $USER 
-  * Now install all of the other core packages that allow you to build the toolchain, nodeMCU and ''​luac.cross'':​+``` 
 +  * Now install all of the other core packages that allow you to build the toolchain, nodeMCU and ''​luac.cross''​.  Note that Ubuntu 12.04 doesn'​t include pre-packaged versions of some of the Lua libraries, so you need to do a ''​luarocks install''​ to build these:
  
 +```
   sudo apt-get install \   sudo apt-get install \
-     ​build-essential zip gdb git vim make unrar autoconf automake \ +     ​build-essential zip gdb git vim make unrar autoconf automake ​gawk 
-     bison texinfo libtool gcc g++ gperf libc-dbg ncurses-dev expat \ +     bison texinfo libtool gcc g++ gperf libc-dbg ncurses-dev expat flex help2man ​
-     ​lua5.1 lua5.1-doc luarocks ​lua-bitop lua-filesystem lua-md5 lua-posix lua-socket +     ​lua5.1 lua5.1-doc luarocks 
-   +  ​for m in bitlib luafilesystem md5 luaposix luasocket; do sudo luarocks install $m; done  
-and you are good to go. +``` 
-=======Using the Arduino IDE.=======+and now you are good to go.  If you want to work on the nodeMCU firmware documentation then you will also need the MkDocs toolkit: 
 + 
 +``` 
 +  sudo apt-get install python-pip 
 +  sudo pip install mkdocs 
 +``` 
 +See the [[http://​www.mkdocs.org/​|MkDocs Website]] for more info. 
 +  
 +=====Using the Arduino IDE.=====
  
 Another Integrated Development Environment (IDE) for programming in C++ and more easier for beginners is the Arduino IDE [[http://​www.arduino.cc/​en/​Main/​Software|http://​www.arduino.cc/​en/​Main/​Software]]. Arduino IDE is an editor that is able to compile the code for us using Xtensa GCC toolchain, which is available at github as ESP8266/​Arduino [[https://​github.com/​esp8266/​Arduino|http:​https://​github.com/​esp8266/​Arduino]]. It also uses the ESPTool to automatically upload the hex to the SOC (system on chip). This repository provides several examples that you can put on the chip, and describes the install instructions for running it. They are as simple as adding the board manager url [[http://​arduino.esp8266.com/​package_esp8266com_index.json]] in the preference settings menu and install it using Tools->​Board->​Board Manager. Another Integrated Development Environment (IDE) for programming in C++ and more easier for beginners is the Arduino IDE [[http://​www.arduino.cc/​en/​Main/​Software|http://​www.arduino.cc/​en/​Main/​Software]]. Arduino IDE is an editor that is able to compile the code for us using Xtensa GCC toolchain, which is available at github as ESP8266/​Arduino [[https://​github.com/​esp8266/​Arduino|http:​https://​github.com/​esp8266/​Arduino]]. It also uses the ESPTool to automatically upload the hex to the SOC (system on chip). This repository provides several examples that you can put on the chip, and describes the install instructions for running it. They are as simple as adding the board manager url [[http://​arduino.esp8266.com/​package_esp8266com_index.json]] in the preference settings menu and install it using Tools->​Board->​Board Manager.
toolchain.txt · Last modified: 2018/01/06 18:53 by fabix