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).
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].
You will also need the [Arduino IDE version 1.6.x or higher][2].
#### Development builds
In the meantime, you can test __UNSTABLE__ development builds automatically generated on these CI build servers:
You can also test __UNSTABLE__ development builds automatically generated every time an update is added to the GitHub repository:
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).
If you prefer, the core software can be used by running only 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].
...
...
@@ -54,18 +54,18 @@ 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.
This will work on Windows, Linux (including ARM) and Mac OS X, with Python >2.7 or >3.4
## Running
1.[Install Ardublockly][5].
2. Install the [Arduino IDE][2] version 1.6.x or higher.
2. Install the [Arduino IDE][2] version 1.6.x or higher (latest version is always recommended).
3. Run Ardublockly as defined in your installation method.
3. Configure Ardublockly to locate the Arduino IDE [following these instructions][6].
## Online Demos
A demo of the current state of Ardublockly main interface can be found in the following two links (to load the code into an Arduino it requires the full Ardublockly application to be downloaded and run on your computer):
A demo of the latest release of Ardublockly main interface can be found in the following two links (to load the code into an Arduino it requires the full Ardublockly application to be downloaded and run on your computer):
- [ ] Update the documentation build script to work on the project root directory like the other build scripts.
- [x] ~~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
- [x] ~~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
- [ ] Add menu to directly select amongst 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.
...
...
@@ -20,50 +20,45 @@
- [ ] 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
- [ ] Remove tkinker file selection and implement an html version
- [ ] Remove tkinker file/directory 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
- [ ] Comprehensive test of server with python 3
- [ ] Test load sketch to board (current test in raspberry pi and ubuntu to load sketches in the IDE) with python 2 and 3
- [ ] Current port list shows all dev/tty, as all Arduinos should be connected by USB this list can be filtered to only show ttyUSBx ports
#### Mac OS X specific
- [ ] Comprehensive test of server with python 2
- [ ] Comprehensive test of server with python 3
- [ ] Test load sketch to board (current test in raspberry pi and ubuntu to load sketches in the IDE) with python 2 and 3
#### Windows specific
- [ ] Comprehensive test of server with python 3
#### Python 3 specific
- [ ]
## Ardublockly front end
- [x] ~~Remove old IDE output text while waiting for a new verify/open/upload~~
- [ ] 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
- [ ] Add tooltips to the action buttons and floating round buttons
- [ ] Add internationalisation, initially only English and Spanish
- [x] ~~Add tooltips to the action buttons and floating round buttons~~
- [ ] Finish adding internationalisation, start with only English and Spanish
## Blockly
- [ ] Merge changes from upstream to add zoom functionality
- [ ] 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~~
- [x] Merge changes from upstream to add zoom functionality
- [ ] Modify zoom icons to be smaller and placed in a different position
- [ ] Arduino setup and loop block can be copy/pasted using keyboard shorcuts, stop this from happening
- [ ] Refactor new variable name to be able to select custom name on single action and asynchronously
#### Blockly changes to feed upstream
#### Blockly changes to submit upstream
- [ ] Any useful changes to the zoom functionality
- [ ] Use of window.prompt
#### Static typing
- [ ] logic_ternary block getType to defines type as that of its inputs
- [ ] logic_null block right now does not return a type, this might change
- [ ] math_number block 'errornumber' type used for debugging, remove
- [ ] math_arithmetic getType to check types of given inputs to decide between int or float. Right now first block within sets the type.
- [ ] math_constrain getType to check types of given inputs to decide between int or float. Right now first block within sets the type.
- [ ] math_arithmetic getType to check types of given inputs to decide between int or float. Right now first block within sets the type.
- [ ] math_constrain getType to check types of given inputs to decide between int or float. Right now first block within sets the type.
- [ ] math_number getType to use regular expressions more efficiently
- [ ] math_on_list to add static type if lists get implemented
- [ ] controls_for getVarType function
...
...
@@ -74,16 +69,15 @@
#### Arduino generator
- [ ] Text trim does not currently generate Arduino valid code
- [] Second part of the generator refactory
- [x] Second part of the generator refactory
#### Arduino blocks
- [ ] Code generator for lists into arrays
- [ ] A lot of blocks go through the entire block tree, which end ups being inefficient. Maybe create a general pass through in the arduino.js file to check everything that needs to be checked in one pass.
- [ ] SPI pin reservation log needs to be refactored for the new board settings
- [x] ~~SPI pin reservation log needs to be refactored for the new board settings~~
- [ ] Create I2C communication blocks with hue 190
- [ ] Update the serial print block to specify explicit type (hex, str, int, etc)
- [ ] Look into all the serial functions and decide what else might fit in
- [ ] Allow to add return statement to the Arduino setup()/loop() functions
- [ ] Allow to add return statement (to exit) inside the Arduino setup()/loop() functions
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.
The application can be categorised in three main components: Python server, HTML/Javascript front end, and desktop wrapper.
The application can be categorised in three main components: Python server, HTML/Javascript front end, and a desktop application 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.
...
...
@@ -11,7 +11,7 @@ The desktop wrapper is based on Electron, which uses node.js. The node.js compon
## 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 triggered in the CI build servers on each repository commit and are hosted in the following links:
Development builds are triggered in the CI build servers on each git commit and are hosted in the following links:
@@ -26,9 +26,9 @@ Git needs to be installed on the system and accessible through the command line
### Python
These build scripts only work on Python 2.7.
These build scripts have been developed and tested only 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 some Python 3 bindings, a single build environment based on Python 2.7 has been be targeted.
While the non-GUI version of Ardublockly (command line server + browser-based GUI) 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 initial 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.
...
...
@@ -39,21 +39,23 @@ py2exe is a Distutils extension to build Python scripts into Windows executable
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].
You can download py2exe from their [official website][4].
##### 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.
[PyInstaller][5] can be easily installed using pip:
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.
```
pip install pyinstaller
```
##### MkDocs
MkDocs is a static page generator specifically designed for documentation using Markdown.
[MkDocs][6] 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.
The project documentation is written and hosted in the [Ardublockly GitHub Wiki][7]. The build script for the documentation pulls its markdown files and converts them into an HTML static site for offline access.
More information about this procedure can be found in [this article][8].
More information about this procedure can be found on [this article][8].
MkDocs can be easily installed using pip:
...
...
@@ -62,9 +64,9 @@ pip install MkDocs
```
### Node.js
Node.js is required to run Electron. It can be downloaded from the [offical website][14].
Node.js is required to run [Electron][9]. It can be downloaded from the [official website][10].
The `npm` package manager should be included with node, which is used to deal with all the desktop wrapper dependencies.
The `npm` package manager should be included with node, which is used to deal with all the Electron application dependencies.
## Build Instructions
...
...
@@ -76,7 +78,7 @@ cd ardublockly
git submodule update --init --recursive
```
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.
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, and 'ardublockly.wiki' in the 'package/ardublocklydocs/' folder. You can run the last git command above in the project root directory to ensure this is the case, otherwise the submodules directories will be empty.
### First step: Python server (platform dependent)
...
...
@@ -133,45 +135,34 @@ 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:
Build the offline documentation by running the `build_docs.py` script from the project root directory:
```
cd package
python build_docs.py
python package\build_docs.py
```
At this point, if continuing with the next steps, is recommended to go back to the project root directory:
```
cd ../
```
This will remove any previous build directory, rebuild it, and remove any temporary files.
## 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:
This step is only meant if you wish to pack the Ardublockly application into a distributable form. You can pack ardublockly running the following command from the project root directory:
```
python package/pack_ardublockly.py
```
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.
The pack script is 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.
## Individual script files descriptions
This part of the documentation is still under work.
