In this document we will install a set of components that are fundamental for the BigClown projects and will help you to get started quickly on your workstation or laptop.

These fundamental components are:

  • The MQTT broker Mosquitto (with client tools)

  • The web-based tool Node-RED for automation flows

  • The process manager PM2 to start the components automatically on boot

  • The Python application BigClown Gateway for MQTT/gateway bridging

Once you install this setup, you will be able to start designing your automation flows quickly and easily.

Requirements

  • Workstation with Windows, macOS or Ubuntu

  • BigClown USB Dongle

  • One of the BigClown IoT kits

Platform Guides

Select the setup procedure on one of the supported operating systems:

If you already have previously installed playground, you can upgrade it at any time:

Playground Setup on Windows

  1. Download and Install bch-playground-windows installer.

    Download Windows Playground from GitHub

    After installation browser is navigated to Node-RED.

  2. Execute BigClown Playground from the Start menu.

  3. Check services with pm2 list, you should get something like:

    C:\Users\michal>pm2 list
    ┌───────────┬────┬──────┬───────┬────────┬─────────┬────────┬─────┬───────────┬────────┬──────────┐
    │ App name  │ id │ mode │ pid   │ status │ restart │ uptime │ cpu │ mem       │ user   │ watching │
    ├───────────┼────┼──────┼───────┼────────┼─────────┼────────┼─────┼───────────┼────────┼──────────┤
    │ mosquitto │ 0  │ fork │ 9872  │ online │ 0       │ 10m    │ 0%  │ 5.4 MB    │ michal │ disabled │
    │ node-red  │ 1  │ fork │ 11420 │ online │ 0       │ 9m     │ 0%  │ 46.0 MB   │ michal │ disabled │
    └───────────┴────┴──────┴───────┴────────┴─────────┴────────┴─────┴───────────┴────────┴──────────┘
    
  4. Restart PC.

  5. Execute BigClown Playground from the Start menu.

  6. Plug the BigClown USB Dongle into a USB port.

  7. List the available devices:

    bcf devices
    

    Example:

    C:\Users\mmu>bcf devices
    COM3
    COM9
    C:\Users\mmu>bcf devices
    COM9
    

    USB Dongle have port COM3.

  8. Upload the latest firmware into the BigClown USB Dongle:

    bcf flash --device ... bigclownlabs/bcf-gateway-usb-dongle:latest
    

    Example:

    bcf flash --device COM3 bigclownlabs/bcf-gateway-usb-dongle:latest
    
  9. Restart Mosquitto and Node-RED:

    pm2 resurrect
    
  10. Start the BigClown Gateway (in the background):

    pm2 start "%BigClownGateway%" --name bcg -- --device ...
    

    Example:

    pm2 start "%BigClownGateway%" --name bcg -- --device com5
    
  11. Tell PM2 to save state:

    pm2 save
    
  12. Open your web browser with the URL: http://localhost:1880/

  13. Continue in the document Playground Starter or with projects:

Playground Upgrade on Windows

  1. Download and install BigClown Playground for Windows:

    Download installer from GitHub

Playground Setup on macOS

  1. Install the driver for the BigClown USB Dongle:

    Download drivers from FTDI
  2. Restart your computer.

  3. Open the Terminal application.

  4. Install Homebrew (unless you already have it).

  5. Upgrade the Homebrew packages:

    brew update && brew upgrade
    
  6. Install Mosquitto server and clients:

    brew install mosquitto
    

    brew services start mosquitto
    
  7. Install Node.js (required by Node-RED).

    brew install node
    
  8. Install Node-RED:

    sudo npm install -g --unsafe-perm node-red
    
  9. Install PM2:

    sudo npm install -g pm2
    
  10. Tell PM2 to run Node-RED:

    pm2 start `which node-red`
    
  11. Tell PM2 to run on boot:

    pm2 save
    

    pm2 startup
    
  12. Install Python 3 (required by the BigClown Firmware Tool and BigClown Gateway).

    brew install python3
    
  13. Update pip (Python Package Manager) to the latest version:

    sudo pip3 install --upgrade --no-cache-dir pip
    
  14. Install the BigClown Firmware Tool:

    sudo pip3 install --upgrade --no-cache-dir bcf
    
  15. Install the BigClown Gateway:

    sudo pip3 install --upgrade --no-cache-dir bcg
    
  16. Plug the BigClown USB Dongle into a USB port.

  17. List the available devices:

    bcf devices
    
  18. Upload the latest firmware into the BigClown USB Dongle:

    bcf update
    

    bcf flash --device ... bigclownlabs/bcf-gateway-usb-dongle:latest
    
  19. Start the BigClown Gateway (in the background):

    bcg --device ...
    
  20. Open your web browser with the URL:

    http://localhost:1880/

  21. Continue in the document Playground Starter.

Playground Upgrade on macOS

  1. Upgrade the Homebrew packages:

    brew update && brew upgrade
    
  2. Upgrade Node-RED:

    sudo npm update -g node-red
    
  3. Upgrade PM2:

    sudo npm update -g pm2
    
  4. Upgrade the BigClown Firmware Tool:

    sudo pip3 install --upgrade --no-cache-dir bcf
    
  5. Upgrade the BigClown Gateway:

    sudo pip3 install --upgrade --no-cache-dir bcg
    

Playground Setup on Ubuntu

  1. Open the Terminal application.

  2. Upgrade all packages:

    sudo apt update && sudo apt upgrade
    
  3. Install Mosquitto server and clients:

    sudo apt install mosquitto mosquitto-clients
    
  4. Install Node.js version 6 (required by Node-RED).

    sudo apt install nodejs nodejs-legacy npm
    
  5. Install Node-RED:

    sudo npm install -g --unsafe-perm node-red
    
  6. Install PM2:

    sudo npm install -g pm2
    
  7. Tell PM2 to run Node-RED:

    pm2 start `which node-red`
    
  8. Tell PM2 to run on boot:

    pm2 save
    

    pm2 startup systemd
    
  9. Install Python 3 (required by the BigClown Firmware Tool and BigClown Gateway):

    sudo apt install python3.5 python3-pip
    
  10. Update pip (Python Package Manager) to the latest version:

    sudo pip3 install --upgrade --no-cache-dir pip
    
  11. Install the BigClown Firmware Tool:

    sudo pip3 install --upgrade --no-cache-dir bcf
    
  12. Install the BigClown Gateway:

    sudo pip3 install --upgrade --no-cache-dir bcg
    
  13. Add yourself to the dialout user group:

    sudo usermod $USER -a -G dialout
    
  14. Plug the BigClown USB Dongle into a USB port.

  15. List the available devices:

    bcf devices
    
  16. Upload the latest firmware into the BigClown USB Dongle:

    bcf update
    

    bcf flash --device ... bigclownlabs/bcf-gateway-usb-dongle:latest
    
  17. Start the BigClown Gateway (in the background):

    bcg --device ...
    
  18. Open your web browser with the URL:

    http://localhost:1880/

  19. Continue in the document Playground Starter.

Playground Upgrade on Ubuntu

  1. Upgrade all the packages:

    sudo apt update && sudo apt upgrade
    
  2. Upgrade Node-RED:

    sudo npm update -g node-red
    
  3. Upgrade PM2:

    sudo npm update -g pm2
    
  4. Upgrade the BigClown Firmware Tool:

    sudo pip3 install --upgrade --no-cache-dir bcf
    
  5. Upgrade the BigClown Gateway:

    sudo pip3 install --upgrade --no-cache-dir bcg