The desktop application is available for Windows/Mac/Linux and runs as a stand-alone executable that can be downloaded from the [Ardublockly repository releases page][4] (once it is stable enough for a first alpha release).
You will also need the [Arduino IDE version 1.6 or higher][2].
You will also need the [Arduino IDE version 1.6.x or higher][2].
In the meantime, you can test __UNSTABLE__ development builds automatically generated on these build servers:
#### Development builds
In the meantime, you can test __UNSTABLE__ development builds automatically generated on these CI build servers:
If you prefer, the main software can be run with Python and a web browser only. Installation instructions for this "developer version" can be found in [this Github repository Wiki][5]. This will work on Windows, Linux and MacOS X, with Python >2.6 and >3.2.
#### "Core version" (Python server only)
If you prefer, the core software can be used by running the Python server, which loads the web interface on your local browser (Chrome recommended).
Full installation instructions for this version can be found in [this Github repository Wiki][5].
The quick version: Clone this repository, initialise all submodules, and execute:
```
python start.py
```
This will work on Windows, Linux (including ARM) and MacOS X, with Python >2.6 and >3.2.
## Running
1.[Install Ardublockly][5].
2. Install the [Arduino IDE][2] version 1.6 or higher.
2. Install the [Arduino IDE][2] version 1.6.x or higher.
3. Run Ardublockly as defined in your installation method.
3. Configure Ardublockly to locate the Arduino IDE [following these instructions][6].
...
...
@@ -55,15 +78,16 @@ A demo of the current state of Ardublockly main interface can be found in the fo
The documentation, including installation instructions, configuration instructions, and developer information can be found in the [Ardublockly GitHub repository Wiki][7].
To download the documentation you can git clone the wiki data:
This project has been inspired by [BlocklyDuino][16].
Blockly original source is Copyright of Google Inc. [https://developers.google.com/blockly/][1]
Blockly original source is Copyright of Google Inc. [https://developers.google.com/blockly/][1]. A list of changes to the Blockly fork can be found in the [Blockly subdirectory README][17] file.
## License
...
...
@@ -73,7 +97,7 @@ The full document can be found in the [LICENSE][9] file.
- [ ] Update the documentation build script to work on the project root directory like the other build scripts.
- [ ] Update the py2exe Windows Build to place the executable on the projetct root directory.
- [ ] Should the Windows build be moved to PyInstaller and keep a single build script for all platforms??
- [ ] Add documentation build steps to the CI build servers
## Ardublockly desktop wrapper
- [ ] Wait for resolution and implement appData directory move fixes https://github.com/atom/electron/issues/2721
- [ ] Move Electron front end changes script from ardublockly html injection into preload script executed from Electron
- [ ] Add menu to directly select a between the different Arduino boards supported
- [ ] Executable app signing
- [ ] Check for "built python server executable", if not found check if python is installed, if it is then run the server in a python subprocess.
## Python server
- [ ] Complete `compilerserttings` module unit test
- [ ] Complete `actions` module unit test module
- [ ] Check for more possible issues with unicode in Python 2
- [ ] Experiment with the `--preserve-temp-files` flag to maintain temporary files and speed up CLI compilation.
- [ ] Experiment with the `--preserve-temp-files` flag to maintain temporary files and speed up CLI compilation
- [ ] Remove tkinker file selection and implement an html version
- [ ] The server should provide fully "headless" execution
#### Linux specific
- [ ] Test load to board in Linux with Arduino 1.6 (current test in raspberry pi and ubuntu to load sketches in the IDE) with python 2
...
...
@@ -16,6 +33,7 @@
- [ ] Comprehensive test of server with python 3
#### Windows specific
- [ ] Comprehensive test of server with python 3
#### Python 3 specific
...
...
@@ -25,14 +43,9 @@
- [ ] Change delete all icon with "new"
- [ ] Similar to Arduino IDE, select area to display button action text, and change the text with button mouse over
- [ ] Ensure that basic empty sketch code shows on page load
- [ ] On low resolutions ensure the blockly vertical height is lower than the viewport
## Ardublockly desktop wrapper
- [ ] Wait for resolution and implement appData directory move fixes https://github.com/atom/electron/issues/2721
- [ ] Move Electron front end changes script from ardublockly html injection into preload script executed from Electron
- [ ] Add menu to directly select a between the different Arduino boards supported
- [ ] Executable app signing
- [ ] On low resolutions ensure the blockly vertical height is lower than the viewport
- [ ] Add tooltips to the action buttons and floating round buttons
- [ ] Add internationalisation, initially only English and Spanish
## Blockly
...
...
@@ -40,7 +53,7 @@
- [ ] Modify zoom icons to be smaller and placed in top right corner
- [ ] Modify zoom to be available without using the scroll
- [x] ~~Add setup and loop functions to the custom toolbox flyout and ensure only one instance can be included in workspace~~
- [ ] Arduino setup and loop block can be copy/pasted using keyboard shorcuts, stop this from happening
- [ ] Arduino setup and loop block can be copy/pasted using keyboard shorcuts, stop this from happening
#### Blockly changes to feed upstream
- [ ] Any useful changes to the zoom functionality
...
...
@@ -57,7 +70,7 @@
- [ ] controls_forEach block uses lists, these are not implemented in the Arduino generator (possible arrays), when implemented this block needs a getVarType, varType, and getType functions
- [ ] add getVarType to the procedures blocks
- [ ] the loops count type is set to int, user could input a decimal, so add input checking to determine type
- [ ] Number blocks automatically trim unnecessary decimal digits "x.0 => x", change this behavior so that "x.0" can be set as a decimal
- [ ] Number blocks automatically trim unnecessary decimal digits "x.0 => x", change this behavior so that "x.0" can be set as a decimal
#### Arduino generator
- [ ] Text trim does not currently generate Arduino valid code
...
...
@@ -75,8 +88,8 @@
## Future features
- [ ] Block creator app that also used blockly to create the generator code
- [ ] Server component of the block creator to add files into folder and client side update to read them and include them into the toolbox
- [ ] Server component of the block creator to add files into project directory folder and have client side to read them and include them into the toolbox
- [ ] Serial console for comms with Arduino
- [ ] Serial data graphing
- [ ] SVG image creation to displayed used pins with given function
- [ ] Auto updating for the desktop app
- [ ] Auto updating from server for the desktop app
The package folder contains the Python scripts required to package Ardublockly into a standalone executable. This way it can be distributed without any dependencies other than having the Arduino IDE.
Currently the Windows build is created using py2exe and the Linux and Mac OS X builds are created using PyInstaller (in the future PyInstaller might be updated to also create the Windows builds, for now the original py2exe script is pretty stable).
The application can be categorised in three main components: Python server, HTML/Javascript front end, and desktop wrapper.
Currently the Python server is packaged using py2exe for Windows, and PyInstaller for Linux and Mac OS X. In the future PyInstaller might be updated to also create the Windows builds, for now the original py2exe script is pretty stable.
The desktop wrapper is based on Electron, which uses node.js. The node.js component is only used where required for the application to integrate well with the individual desktop platforms. Originally the Chromium Embedded Framework Python bindings were used, but cross-platform maintenance proved to be problematic and Electron has provided a much smother alternative.
## Download the packaged Ardublockly
The stable binaries for Windows, Linux, and Mac OS X are hosted in GitHub as part of the [repository releases][1].
Development builds are frequently triggered in build servers and hosted in the following link: [Dev builds][10]
Development builds are triggered in the CI build servers on each repository commit and are hosted in the following links:
Git needs to be installed on the system and accessible through the command line interface.
### Python
### Python
These build scripts only work on Python 2.7.
While the non-GUI version of Ardublockly (command line server + pre-installed browser) is compatible with other Python versions (tested on Python 2.7 and 3.4), due to the individual perks of the python libraries used here and unavailability of CEF Python 3 bindings, a single build environment based on Python 2.7 will be targeted.
While the non-GUI version of Ardublockly (command line server + pre-installed browser) is compatible with other Python versions (tested on Python 2.7 and 3.4), due to the individual perks of the python libraries used here and unavailability of some Python 3 bindings, a single build environment based on Python 2.7 has been be targeted.
If you are using Python virtual environments on Windows this [collection of Python extensions binaries][2] is highly recommended.
The specific versions of the Python dependencies can be found in the [requirements.txt][3] file.
#### cefpython3
CEF Python provides Python bindings for the Chromium Embedded Framework. This is used in Ardublockly to create a webview of the Ardublockly web app without requiring any specific browser installation. This is specially useful for the project because the frameworks used work best on the Chrome engine.
[Install cefpython following their project installation instructions][5]. On Windows and Mac OS X cefpython can be easily installed using pip:
```
pip install cefpython3
```
#### wxPython
wxPython provides python bindings for the wxWidgets, the cross-platform GUI toolkit.
You can download wxPython from their [official website][4].
(I have recently found some odd issues in Ubuntu 15.04 when cefpython is running with wxPython version 3.0.2.0, reverting back to the 2.8.12.1 version seemed to fix them.)
#### py2exe
py2exe is a Distutils extension to build Python scripts into Windows executable programs.
##### py2exe
py2exe is a Distutils extension to build Python scripts into Windows executable programs.
This package is only required for the Windows build. The Linux and Mac OS X builds use the PyInstaller scripts included in this folder.
You can download py2exe from their [official website][6].
#### PyInstaller
##### PyInstaller
Converts (packages) Python programs into stand-alone executables, used for the Linux and Mac OS X builds.
This package does not need to be installed, as it is already included in this folder.
This version of PyInstaller is from the official [repository wiki][9]. As the version stored in Pypi is quite old, pip would install an outdated version that won't work with the current specs file.
This version of PyInstaller is from the official [repository wiki][9]. As the version stored in Pypi, at the time of writting, is quite old, pip would install an outdated version that won't work with the current specs file.
#### MkDocs
##### MkDocs
MkDocs is a static page generator specifically designed for documentation using Markdown.
The project documentation is written and hosted in the [Ardublockly repository GitHub Wiki][7]. The build script for the documentation pulls its markdown files and converts them into an HTML static site for offline access.
...
...
@@ -73,8 +61,13 @@ MkDocs can be easily installed using pip:
pip install MkDocs
```
### Node.js
Node.js is required to run Electron. It can be downloaded from the [offical website][14].
The `npm` package manager should be included with node, which is used to deal with all the desktop wrapper dependencies.
## Build steps
## Build Instructions
Download and initialise this project repository:
```
...
...
@@ -83,17 +76,11 @@ cd ardublockly
git submodule update --init --recursive
```
If you have already downloaded the Ardublockly source code, make sure the submodules are initialise, in this case the 'closure-library' in the project root directory and 'pyinstaller' in the package folder. You can run `git submodule update --init --recursive` in the project root to ensure this is the case, otherwise the submodule directories will be empty.
If you have already downloaded the Ardublockly source code, make sure the submodules are initialised, in this case the 'closure-library' in the project root directory, 'pyinstaller' in the package folder, and 'ardublockly.wiki' in the 'package/ardublocklydocs/' folder. You can run the git command above in the project root directory to ensure this is the case, otherwise the submodule directories will be empty.
First build the offline documentation by running the `build_docs.py` script from within the package folder. This will add a folder named `documentation` into the project root directory:
```
cd package
python build_docs.py
```
The build steps for Ardublockly are slightly different depending on the platform.
### First step: Python server (platform dependent)
The build steps for the Ardublockly Server are slightly different depending on the platform.
### Windows Build
To build Ardublockly under Windows all you have to do is execute the `build_windows.py` file from the project root directory:
This will remove any previous build directory, rebuild, and create the `ardublockly_run.bat` file into the project root.
To run Ardublockly on Windows execute the `ardublockly_run.bat` file.
### Linux Build
To build Ardublockly under Linux all you have to do is execute the `build_linux.py` file from the project root directory:
To build Ardublockly under Linux all you have to do is execute the `build_pyinstaller.py` file from the project root directory:
```
python package/build_linux.py
python package/build_pyinstaller.py
```
The optional flag `linux` can be provided, but the operating systems should be automatically detected.
This will remove any previous build directory, rebuild, and create the `ardublockly_run.sh` file into the project root.
To run Ardublockly on Linux execute the `ardublockly_run.sh` bash file. Don't forget set the file as executable to be able to run it from your desktop environment.
### Mac OS X Build
To build Ardublockly under Mac OS X all you have to do is execute the `build_pyinstaller.py` file from the project root directory:
```
python package/build_pyinstaller.py
```
### Mac OS X Build
This part of the documentation is still under work.
The optional flag `mac` can be provided, but the operating systems should be automatically detected.
This will remove any previous build directory, and rebuild it.
## Second step: Electron (platform independent)
Execute the following commands from the project root directory:
```
cd package\electron
npm install
npm run release
```
The npm scripts will automatically detect and deal with the operating system different build requirements.
At this point, if continuing with the next steps, is recommended to go back to the project root directory:
```
cd ../../
```
## Third step: Documentation (platform independent)
Build the offline documentation by running the `build_docs.py` script from within the package folder. This will add a folder named `documentation` into the project root directory:
```
cd package
python build_docs.py
```
At this point, if continuing with the next steps, is recommended to go back to the project root directory:
```
cd ../
```
## Packing Ardublockly
## Final Step: Packing all Ardublockly (platform independent)
Once the project is build there are a few unnecessary files that can be removed to save space.
You can pack ardublockly running the following command from the project root directory:
The pack script was designed for the build servers to zip the required contents into a single file to be uploaded to cloud storage, so it still leaves quite a few things behind. This script creates a new folder on the same level a the project root, and then zips it and saves it into the folder 'upload' within the project root.
## Script files descriptions:
## Individual script files descriptions
This part of the documentation is still under work.
