Install Free Trial

This section is for installing the free trial binaries on devices. If you purchased a Nebula package you can skip to Development.

Download the free trial. Save the InstallNebula.zip file to your Downloads folder.

  • The installation instructions were written using the following computers - operating systems for verification:

    * Dell XPS 8900 - Ubuntu Linux 18.04
    * Dell XPS 8900 - Windows 10
    * Apple iMac (late 2015) - MacOS Mojave version 10.14
    * Multiple phones/pads - Android OS 4.4.2 to 9.0
    * Raspberry Pi 3 B+ - Raspian 2019-06-20 Linux
    * BeagleBone Black revs. A6A & C - Debian 9.9 Linux
    * MakerFocus ESP8266 NodeMCU ESP-12E - Arduino Nebula 1.0
    
  • Due to Nebula being multi-platform different binary programs are used depending on the type of device it is being installed on.

    * Linux, Windows and Mac use nebula.jar
      Document references to JAR devices are
      Linux, Windows or Mac.
    
    * Android uses nebula.apk
      Document references to APK devices are Android.
    
    * NodeMCU/8266 uses nebula.bin
      Document references to BIN devices are NodeMCU.
    
    * Arduino boards with a network connection use nebula.hex
      Document references to HEX devices are Arduino.
    
  • The software tools used for installing the Nebula binaries are included in the installation folder. They are freely available at the following locations:

    https://www.xda-developers.com/install-adb-windows-macos-linux/
    https://dl.google.com/android/repository/platform-tools-latest-windows.zip
    https://dl.google.com/android/repository/platform-tools-latest-darwin.zip
    https://dl.google.com/android/repository/platform-tools-latest-linux.zip
    https://github.com/espressif/esptool
    

Nebula on Linux

The installation requires the use of Terminal.

  • To open a Terminal window: Show Applications > Search for Terminal

All required commands can be copied and then pasted to the Terminal command line for execution.

Linux Extract the Install Files

1. Starting with the InstallNebula.zip file in your Downloads folder.
1.1. Move the file to your Desktop.
mv $HOME/Downloads/InstallNebula.zip $HOME/Desktop/

2. Right-click the InstallNebula.zip file and select Extract Here.

3. You can now delete or move the .zip file from your desktop to some other location for later use.

Note: do not create a folder named “Nebula” in your home directory. $HOME/Nebula is reserved for Nebula device database and file transfer use.

4. You should now have a folder called InstallNebula on your desktop.

5. Inside the InstallNebula folder are 5 folders:

Binaries:
nebula.apk  nebula.bin  nebula.jar

ESP_Tools:
esptool-master.zip

Linux_Tools:
platform-tools_r29.0.2-linux.zip

Mac_Tools:
platform-tools_r29.0.2-darwin.zip

Windows_Tools:
platform-tools_r29.0.2-windows.zip

Java for Linux

1. Open a Terminal window and check your Java version:

java -version

2. The nebula.jar is ready to run if the computer has Java version 8 or greater installed on it. If you have to install or update Java go here.

3. To start Nebula:

cd $HOME/Desktop/InstallNebula/Binaries && java -jar nebula.jar

4. The Nebula New Device Setup screen should now be showing.

../_images/Install-JAR.png

5. Copy the nebula.jar file to other Linux devices you intend to include on your VPN, or follow the instructions for other devices, until you have the Device Setup screen showing on at least 2 devices.

Review the notes regarding Device 1 before continuing.

Install Java on Linux

Here’s a good tutorial: https://thishosting.rocks/install-java-ubuntu/

1. Check if your computer is 32 or 64 bit.

uname -m
  • If the response is “x86_64”, then you have a 64-bit computer.
  • If the response is “i686”, then you have a 32-bit computer.

2. Go to the Oracle download page.

If your computer is 32 bit or if you just want Java 8 for your 64 bit computer, then scroll down and select Java SE 8u<version> - JDK Download.

If your computer is 64 bit the recommended package is the latest LTS (Long Term Support) package available. At the time of this writing (10/2019) it was 11.04. See step 4.

3. Click DOWNLOAD on the JDK package you want. From the Oracle download screen, first accept the License Agreement then select the download for your OS. You will have to create or have an existing account with Oracle to get the download.

Here are the Oracle instructions for Java 8

4. For Java 11 or higher get the Linux .deb download.
Move the downloaded installer to your Desktop.
mv $HOME/Downloads/jdk-*.deb $HOME/Desktop

5. Install Java by running the following command.

sudo apt install $HOME/Desktop/jdk-package.version.deb

6. Verify the installation with:

java -version

7. Now you should see:

java version “11.0.4” 2019-07-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.4+10-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.4+10-LTS, mixed mode)
  • Showing Java 11 - Your installed version may be different.

May have to manually add Java to Linux PATH

  1. append to ~/.bashrc - PATH=$PATH:/full/path/to/bin/java
  2. source .bashrc - rerun .bashrc
  3. java -version - check it is working

Install APK from Linux

Sideloading is the common term for installing an app without downloading directly from the Google Play Store. Sideloading the Nebula app on an Android device requires that the phone or tablet be connected to your computer with a USB data cable. Then, by using Android Debug Bridge (ADB), you can install the app over the USB connection.

1. Open the InstallNebula/Linux_Tools folder and extract the ADB tool file:
platform-tools_ rev.num -linux.zip

2. Enable “Developer options” for USB debugging on the Android device.

1. Open Settings or on Android 8.0 or higher Select System.
2. Scroll to and select About phone.
3. Scroll to and tap Build number 7 times.
4. Go back to Settings and find Developer options near the bottom.
5. Open Developer options. Scroll to and enable USB debugging

3. Attach the device to your computer with a USB data cable and allow access if requested.

4. Move to the extracted tools directory.

cd $HOME/Desktop/InstallNebula/Linux_Tools/platform-tools*-linux/platform-tools

5. Verify only one device is attached.

./adb devices
Response:
List of devices attached
“hex value ID” device <– See only one device

6. Install the Nebula app to device internal memory OR skip to the next step and install to SD card.

./adb install $HOME/Desktop/InstallNebula/Binaries/nebula.apk

7. OPTIONAL - Install to device SD card

./adb install -s $HOME/Desktop/InstallNebula/Binaries/nebula.apk

8. Verify installation

./adb shell pm list packages -3 | grep galixsys

Response: package:com.galixsys.nebula

9. Stop the adb server

./adb kill-server

10. To open the installation screen on the Android device, select Apps > Nebula.

11. Newer Android devices require the user to allow permission for some app actions. If you are alerted “This device needs permission”, click OK. The Nebula app settings screen will come up.

11.1- Scroll to and select the Permissions settings.
11.2- Allow all listed, here is why and how they are used in Nebula.
11.3- After allowing permissions, click the device’s Back button.

12. If the device is provisioned and can go mobile you will be presented with another alert asking for email details. You can enter the details for Nebula Mobile now or click Cancel to get familiar with Nebula on WiFi before going mobile. The end result is to get the Installation screen showing on the device.

13. Repeat this Nebula installation procedure for any other Android devices you want to include on your VPN. Remember that only 1 Android device can be connected at a time when Sideloading, and you have to uninstall Nebula before you can reinstall it.

14 Review the notes regarding Device 1 before continuing.

Install BIN from Linux

Python and Pyserial are required to install Nebula on NodeMCU/8266 modules. Python is typically installed by default, Pyserial is not. In order to install Pyserial you also need the Python installer package “pip”. The next few steps will walk you through the process. You will need to know the Administrator password for the computer in order to install packages.

1. Update the package manager.

sudo apt-get update

2. Check for Python

python --version

Response: Python 2.7.x or 3.4.x or 3.7.x

3.1 If the response starts with 2:

sudo apt-get install pip
pip install pyserial

3.2 If the response starts with 3:

sudo apt-get install python3-pip
pip3 install pyserial

4. Open the InstallNebula/ESP_Tools folder and extract the ESP tool file esptool-master.zip

5. Attach the NodeMCU module to your computer with a USB data cable.

6. Determine which port it attached to.

dmesg | tail

7. On or near the last line of the response you will see “cp210x converter now attached to ttyUSB0”. Make note of the port it’s attached to, it may not be ttyUSB0.

8. Move to the ESPtools extracted directory.

cd $HOME/Desktop/InstallNebula/ESP_Tools/esptool-master

9. You will have to edit the next command if you are using Python 3 and/or the ESP module is not attached to port ttyUSB0.

  • For Python 3: Start the command using python3 instead of python.
  • For a different port: Replace the “ttyUSB0” with the port noted above.
9.1 To edit the command:
  1. Copy the command from the documentation.
  2. Paste it in Text Editor.
  3. Edit the command as required.
  4. Copy the edited command.
  5. Paste it on the Terminal command line.
  6. Hit Enter.
python ./esptool.py --port /dev/ttyUSB0 write_flash 0x00000 ../../Binaries/nebula.bin

10. With the Nebula program now installed you will want to watch the log output while the module first gets connected to your home network, followed by setting it up on your VPN. To see the log on the Terminal window you may first have to have permission to access your computer serial ports. Add yourself to the dialout group with the command:

sudo usermod -a -G dialout $USER

11. The next command sets up Terminal for reading and display of serial text. You may have to edit the /dev/ttyUSB0 in 2 places to match the the port discovered in step 6. You can also skip this command and install Putty to monitor the serial output.

stty -F /dev/ttyUSB0 cs8 115200 ignbrk -brkint -icrnl -imaxbel -opost -onlcr -isig -icanon -iexten -echo -echoe -echok -echoctl -echoke noflsh -ixon -crtscts && tail -f /dev/ttyUSB0

11.1 OPTIONAL: Putty is a very useful program for monitoring serial ports and is available for Linux:

sudo apt install putty

11.2 Open Putty and set to Serial, Serial line to /dev/ttyUSB0 or as noted, Speed to 115200, then click Open.

../_images/PuttyLinux.png

12. Now Install the module to get to the installation screen.

../_images/Install-BIN.png

Review the notes regarding Device 1 before continuing.

Nebula on Windows

The installation requires the use of PowerShell.

  • To open a PowerShell window: StartMenu > Search > PowerShell (app)

All required commands can be copied and then pasted to the command line for execution.

Windows Extract the Install Files

1. Starting with the InstallNebula.zip file in your Downloads folder.
1.1. Move the file to your Desktop.
mv $HOME/Downloads/InstallNebula.zip $HOME/Desktop/

2. Right-click the InstallNebula.zip file and select Extract All…

3. In the resulting window. Remove the InstallNebula directory from the default install path. This will avoid having the install folder inside a folder of the same name. Then click Extract. Close any windows and you can now discard or move the .zip file from your desktop.

Note: do not create a folder named “Nebula” in your home directory. $HOME/Nebula is reserved for Nebula device database and file transfer use.

4. You should now have a folder called InstallNebula on your desktop.

5. Inside the LinuxInstall folder are 5 folders:

Binaries:
nebula.apk  nebula.bin  nebula.jar

ESP_Tools:
esptool-master.zip

Linux_Tools:
platform-tools_r29.0.2-linux.zip

Mac_Tools:
platform-tools_r29.0.2-darwin.zip

Windows_Tools:
platform-tools_r29.0.2-windows.zip

Java for Windows

1. Open a Power Shell window and check your Java version:

java -version

2. The nebula.jar is ready to run if the computer has Java version 8 or greater installed on it. To install or update Java go here

3. To start Nebula:

cd $HOME\Desktop\InstallNebula\Binaries; java -jar nebula.jar

4. The Nebula New Device Setup screen should now be showing.

../_images/Install-JAR.png

5. Copy the nebula.jar file to other Windows devices you intend to include on your VPN, or follow the instructions for other devices, until you have the Device Setup screen showing on at least 2 devices.

Review the notes regarding Device 1 before continuing.

Install Java on Windows

The Oracle install directions:

1. Download the latest LTS (Long Term Support) package available. At the time of this writing (10/2019) it was 11.04. Accept the License Agreement then select the download for your OS. You may have to create an account with Oracle to get the download.

  • For Windows get the .exe installer.

2. Move the downloaded installer to your Desktop. Double-click the installer, check the Add to Path box, then follow the install instructions.

2.1 How to manually add Java to Windows PATH. Not necessary if done by the installer.

1. Search for "envi" select the Control Panel
2. Click Environment Variables
3. Under System Variables - Add or Edit JAVA_HOME
4. Variable value C:\Program Files\Java\jdk-11.0.4
5. Save the System Variable
6. Under User Variable - select Path
7. Add the line "%JAVA_HOME%\bin" without quotes if not there already
8. Click OK

3. Verify the installation with:

java -version

4. Now you should see:

java version “11.0.4” 2019-07-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.4+10-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.4+10-LTS, mixed mode)
  • Showing Java 11 - Your installed version may be different.

Install APK from Windows

Sideloading is the common term for installing an app without downloading directly from the Google Play Store. Sideloading the Nebula app on an Android device requires that the phone or tablet be connected to your computer with a USB data cable. Then, by using Android Debug Bridge (ADB), you can install the app over the USB connection.

1. Open the InstallNebula/Windows_Tools folder and extract the ADB tool file
platform-tools_ rev.num-windows.zip

2. Enable “Developer options” for USB debugging on the Android device.

1. Open Settings or on Android 8.0 or higher Select System.
2. Scroll to and select About phone.
3. Scroll to and tap Build number 7 times.
4. Back to Settings and find Developer options near the bottom.
5. Open Developer options. Scroll to and enable USB debugging.

3. Attach the device to your computer with a USB data cable and allow access if requested.

4. Move to the extracted tools directory.

cd $HOME\Desktop\InstallNebula\Windows_Tools\platform-tools*-windows\platform-tools

5. Verify only one device is attached.

.\adb devices
Response:
List of devices attached
“hex value ID” device <– See only one device

6. Install the Nebula app to device internal memory OR skip to the next step and install to SD card.

.\adb install ..\..\Binaries\nebula.apk

7. OPTIONAL - Install to device SD card

.\adb install -s ..\..\Binaries\nebula.apk

8. Verify installation

./adb shell pm list packages -3 | grep galixsys

Response: package:com.galixsys.nebula

9. Stop the adb server

.\adb kill-server

10. To open the installation screen on the Android device, select Apps > Nebula.

11. Newer Android devices require the user to allow permission for some app actions. If you are alerted “This device needs permission”, click OK. The Nebula app settings screen will come up.

11.1- Scroll to and select the Permissions settings.
11.2- Allow all listed, here is why and how they are used in Nebula.
11.3- After allowing permissions, click the device’s Back button.

12. If the device is provisioned and can go mobile you will be presented with another alert asking for email details. You can enter the details for Nebula Mobile now or click Cancel to get familiar with Nebula on WiFi before going mobile. The end result is to get the Installation screen showing on the device.

13. Repeat this Nebula installation procedure for any other Android devices you want to include on your VPN. Remember that only 1 Android device can be connected at a time when Sideloading, and you have to uninstall Nebula before you can reinstall it.

14 Review the notes regarding Device 1 before continuing.

Install BIN from Windows

Python and Pyserial are required to install Nebula on NodeMCU/8266 modules. Python is not typically installed on Windows by default. The next few steps will walk you through the process of installing Python 3.7 and Pyserial.

1. Go to https://www.python.org/downloads/windows/ and download an appropriate installer.

2. Move the installer to your Desktop then double-click it.

3. Check the box to add Python to your path.

4. Restart your computer to let Python be fully discovered.

5. Open PowerShell

python --version

Response: Python 3.7.4

6. Install pyserial:

pip install pyserial

7. Open the InstallNebula/ESP_Tools folder and extract the ESP tool file esptool-master.zip

8. Attach the NodeMCU module to your computer with a USB data cable.

9. Open Settings > Devices, scroll down to and find the line “Silicon Labs CP210x USB to UART Bridge(COM3)”

Make note of the port(COM) it’s attached to, it may not be COM3.

10. Move to the ESPtools extracted directory.

cd $HOME\Desktop\InstallNebula\ESP_Tools\esptool-master

11. You will have to edit the next command if the ESP module is not attached to port COM3.

  • For a different port: Replace the “COM3” with the port noted above.

11.1 To edit the command:

  1. Copy the command from the documentation.
  2. Paste it in Notepad.(TODO: Try, I used notepad++)
  3. Edit the command as required.
  4. Copy the edited command.
  5. Paste it on the Terminal command line.
  6. Hit Enter.
python .\esptool.py --port COM3 write_flash 0x00000 ..\..\Binaries\nebula.bin

12. With the Nebula program now installed you will want to watch the log output while the module first gets connected to your home network, followed by setting it up on your VPN. To see the log use Putty.

12.1 You can get Putty from here https://www.putty.org/

12.2 Move the installer to your Desktop, double-click it then follow the instructions to install it.

12.3 Open Putty using the shortcut.

13. Set Putty to Serial, Serial line to COM port noted, Speed to 115200, then click Open.

../_images/Putty.png

14. Now Install the module to get to the installation screen.

../_images/Install-BIN.png

Review the notes regarding Device 1 before continuing.

Nebula on Mac

The installation requires the use of Terminal.

  • To open a Terminal window: Finder > Applications > Utilities > Terminal

All required commands can be copied and then pasted to the command line for execution.

Mac Extract the Install Files

1. Starting with the InstallNebula.zip file in your Downloads folder.
1.1 Move the file to your Desktop.
mv $HOME/Downloads/InstallNebula.zip $HOME/Desktop/

2. Double-click the InstallNebula.zip file and it will be extracted to your desktop.

3. You can now discard or move the .zip file from your desktop.

Note: do not create a folder named “Nebula” in your home directory. $HOME/Nebula is reserved for Nebula device database and file transfer use.

4. You should now have a folder called InstallNebula on your desktop.

5. Inside the LinuxInstall folder are 5 folders:

Binaries:
nebula.apk  nebula.bin  nebula.jar

ESP_Tools:
esptool-master.zip

Linux_Tools:
platform-tools_r29.0.2-linux.zip

Mac_Tools:
platform-tools_r29.0.2-darwin.zip

Windows_Tools:
platform-tools_r29.0.2-windows.zip

Java for MacOS

1. Check your Java version:

java -version

2. The nebula.jar is ready to run if the computer has Java version 8 or greater installed on it. To install or update Java go here.

3. To start Nebula, use the next command to see the log output OR right-click the nebula.jar file and then click Open:

cd $HOME/Desktop/InstallNebula/Binaries && java -jar nebula.jar

4. The Nebula New Device Setup screen should now be showing.

../_images/Install-JAR.png

5. Copy the nebula.jar file to other Mac devices you intend to include on your VPN, or follow the instructions for other devices, until you have the Device Setup screen showing on at least 2 devices.

Review the notes regarding Device 1 before continuing.

Install Java on MacOS

First install and update brew from Terminal using the next 3 commands:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew tap caskroom/versions
brew update

New way - As of June 2019

To install the JDKs from AdoptOpenJDK:

brew tap adoptopenjdk/openjdk

Then this for Java 8

brew cask install adoptopenjdk8

Or this for Java 11

brew cask install adoptopenjdk11

Old way

Java 8:

brew cask install java8

Java Latest:

brew cask install java

Install APK from Mac

Sideloading is the common term for installing an app without downloading directly from the Google Play Store. Sideloading the Nebula app on an Android device requires that the phone or tablet be connected to your computer with a USB data cable. Then, by using Android Debug Bridge (ADB), you can install the app over the USB connection.

1. Open the InstallNebula/Mac_Tools folder and extract the ADB tool file
platform-tools_ rev.num -darwin.zip

2. Enable “Developer options” for USB debugging on the Android device.

1. Open Settings or on Android 8.0 or higher Select System.
2. Scroll to and select About phone.
3. Scroll to and tap Build number 7 times.
4. Go back to Settings and find Developer options near the bottom.
5. Open Developer options. Scroll to and enable USB debugging

3. Attach the device to your computer with a USB data cable and allow access if requested.

4. Move to the extracted tools directory.

cd $HOME/Desktop/InstallNebula/Mac_Tools/platform-tools*-darwin/platform-tools

5. Verify only one device is attached.

./adb devices
Response:
List of devices attached
“hex value ID” device <– See only one device

6. Install the Nebula app to device internal memory OR skip to the next step and install to SD card.

./adb install $HOME/Desktop/InstallNebula/Binaries/nebula.apk

7. OPTIONAL - Install to device SD card

./adb install -s $HOME/Desktop/InstallNebula/Binaries/nebula.apk

8. Verify installation

./adb shell pm list packages -3 | grep galixsys

Response: package:com.galixsys.nebula

9. Stop the adb server

./adb kill-server

10. To open the installation screen on the Android device, select Apps > Nebula.

11. Newer Android devices require the user to allow permission for some app actions. If you are alerted “This device needs permission”, click OK. The Nebula app settings screen will come up.

11.1- Scroll to and select the Permissions settings.
11.2- Allow all listed, here is why and how they are used in Nebula.
11.3- After allowing permissions, click the device’s Back button.

12. If the device is provisioned and can go mobile you will be presented with another alert asking for email details. You can enter the details for Nebula Mobile now or click Cancel to get familiar with Nebula on WiFi before going mobile. The end result is to get the Installation screen showing on the device.

13. Repeat this Nebula installation procedure for any other Android devices you want to include on your VPN. Remember that only 1 Android device can be connected at a time when Sideloading, and you have to uninstall Nebula before you can reinstall it.

14 Review the notes regarding Device 1 before continuing.

Install BIN from Mac

TODO: Verify and Edit - This was copied from InstallBINfromLinux.rst with only the tool name changed from linux to mac

Python and Pyserial are required to install Nebula on NodeMCU/8266 modules. Python is typically installed by default, Pyserial is not. In order to install Pyserial you also need the Python installer package “pip”. The next few steps will walk you through the process. You will need to know the Administrator password for the computer in order to install packages.

About Homebrew the package manager for OSX

1. First install and update brew from Terminal using the next 3 commands:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew tap caskroom/versions
brew update

2. Check for Python

python --version

Response: Python 2.7.x or 3.4.x or 3.7.x

3.1 If the response starts with 2:

sudo brew install pip
pip install pyserial

3.2 If the response starts with 3:

sudo brew install python3-pip
pip3 install pyserial

4. Open the InstallNebula/ESP_Tools folder and extract the ESP tool file esptool-master.zip

5. Attach the NodeMCU module to your computer with a USB data cable.

6. Determine which port it attached to.

sudo dmesg | tail

7. On or near the last line of the response you will see “cp210x converter now attached to ttyUSB0”.

Make note of the port it’s attached to, it may not be ttyUSB0.

8. Move to the ESPtools extracted directory.

cd $HOME/Desktop/InstallNebula/ESP_Tools/esptool-master

9. You will have to edit the next command if you are using Python 3 and/or the ESP module is not attached to port ttyUSB0.

  • For Python 3: Start the command using python3 instead of python.
  • For a different port: Replace the “ttyUSB0” with the port noted above.
9.1 To edit the command:
  1. Copy the command from the documentation.
  2. Paste it in Text Editor.
  3. Edit the command as required.
  4. Copy the edited command.
  5. Paste it on the Terminal command line.
  6. Hit Enter.
python ./esptool.py --port /dev/ttyUSB0 write_flash 0x00000 ../../Binaries/nebula.bin

10. With the Nebula program now installed you will want to watch the log output while the module first gets connected to your home network, followed by setting it up on your VPN.

11. Putty is a very useful program for monitoring serial ports and is available for Mac:

sudo brew install putty

11.1 Add a shortcut icon to Putty on your desktop.

cp /opt/local/bin/putty ~/Desktop/PuTTY

11.2 Open Putty and set to Serial, Serial line as noted without the /dev/, Speed to 115200, then click Open.

../_images/Putty.png

12. Now Install the module to get to the installation screen.

../_images/Install-BIN.png

Review the notes regarding Device 1 before continuing.