Particle SDK Release Candidate 1 (RC1) Downloads
Installation Files
Installing the Particle SDK
The Particle SDK is a modular toolkit for building portable applications. This guide describes how to install the Particle SDK.
Follow these steps to install the Particle SDK:
- Check Installation Requirements
- Install the Java Development Kit (JDK)
- Install Python and PIL (Windows)
- Install Python and PIL (OS X)
- Install the Eclipse IDE
- Uninstall any Existing Particle SDK Installation
- Install or Upgrade the Particle SDK
- Get Started with the Particle Platform
If you are upgrading to RC1 from the Public Beta version of the Particle SDK, please review the RC1 Release Notes before upgrading the SDK.
When upgrading, you do not need to re-install any of the prerequisite software (steps 1 through 5). Skip directly to step 6, Uninstall any Existing Particle SDK Installation.
Check Installation Requirements
The Particle Platform can be installed on any platform that supports Java, Python, and the Eclipse IDE. The following platforms are officially supported:
- Windows (XP, Vista or 7)
- Mac OS X (10.5 or newer)
Install the Java Development Kit (JDK)
The Particle Platform requires the Java SE 6 Development Kit (JDK). Download the latest version of the JDK from:
java.sun.com/javase/downloads/index.jsp
NOTE: JDK 7 is not supported.
The required JDK is preinstalled on Mac OS X 10.5 and 10.6. On 10.7 (Lion), Java is an optional download. The first time you run anything that requires Java (such as Eclipse), the operating system should prompt you to download and install Java. If this doesn’t happen automatically, you can find a downloadable package for 10.7 from:
Both 32-bit and 64-bit versions of Java are available for Windows. If you are running a 64-bit Windows OS, you can use either version, with the following caveats:
- You must install a matching version of Eclipse (that is, 64-bit Eclipse with 64-bit Java).
- If you are planning on using the ActionScript 3 input language, or producing output for the Flash platform, you should use the 32-bit versions of Java and Eclipse.
On Mac OS X, the preinstalled version of Java is always 64-bit if the system has a 64-bit kernel.
Follow the installation instructions appropriate for your system. Make a note of the installation directory.
Add Java To the Search Path
After installing Java, you should make sure that your PATH environment variable includes the Java bin directory. For example:
C:\Java\jdk16.0_22\bin
For information on setting environment variables, see:
www.java.com/en/download/help/path.xml
Install Python and PIL (Windows)
The Particle Platform requires the Python programming language and the Python Imaging Library:
- Python version 2.6
- Python Imaging Library (PIL) 1.1.7 or newer
The Particle Platform will not work with Python 2.7 or Python 3 distributions.
For Windows, download the 32-bit versions of Python and PIL. Download a Python 2.6 distribution from:
www.python.org/download/releases/2.6.6/
After installing Python, install the Python Imaging Library (PIL). You can download an installer for Windows:
www.pythonware.com/products/pil/
Several versions of PIL are available. Be sure to download the version for Python 2.6.
Install Python and PIL (OS X)
The Particle Platform requires the Python programming language and the Python Imaging Library:
- Python version 2.6
- Python Imaging Library (PIL) 1.1.7 or newer
The Particle Platform will not work with Python 2.7 or Python 3 distributions.
OS X comes with a version of Python installed, but there is no compatible installer for PIL, and customers have reported a great deal of difficulty installing PIL with the stock version of Python. In addition, on OS X Leopard (10.5) and Lion (10.7), the stock version of Python is not the correct version for the Particle SDK. It is strongly recommended that you install Python 2.6 and PIL using either MacPorts or the Homebrew Package Installer. PIL can also be built from source if you prefer.
NOTE: Both Homebrew and MacPorts require that you have Xcode installed. These tools are designed to automate the process of building packages (in this case, Python and PIL) from source. Because they may need to download and build multiple dependencies, this process may be time-consuming.
Make a note of the directory where Python is installed. You will need this information when installing the Particle Platform.
Installing Python and PIL using Homebrew
If you don’t have Homebew installed, install it following the directions on the Homebrew home page:
https://github.com/mxcl/homebrew/wiki/installation
If you already have Homebrew installed and have installed Python 2.7 (the current default version), first uninstall Python 2.7 by running the following commands from a Terminal command prompt:
brew uninstall python
Then install Python 2.6 and PIL:
wget https://raw.github.com/gist/971441/4257ebabfeb529f4fe4008bcdb0bf71596d06923/ python26.rb brew install python26 brew install pil
By default, brew installs Python in:
/usr/local/Cellar/python26/<version>
Where <version> is the three-digit version number (for example, 2.6.6).
Installing Python and PIL using MacPorts
To install MacPorts, see the following page:
http://www.macports.org/install.php
If you have MacPorts installed, you can install Python and PIL by running the following commands from a Terminal command prompt:
sudo port install python26 sudo port install py26-pil
By default, MacPorts installs Python in:
/opt/local/Library/Frameworks/Python.framework/Versions/2.6
Install the Eclipse IDE
The Particle Platform depends on the Eclipse IDE. The Particle Platform works with Eclipse Indigo (3.7), Helios (3.6), Galileo (3.5), or Ganymede (3.4). Version 3.5.2 or newer is recommended for best results.
Note that if you are planning on working with Flash, the Adobe Flex Builder 3 Plug-in only works with Eclipse Ganymede, but the newer Adobe Flash Builder 4 Plug-in supports newer versions of Eclipse.
There are many different Eclipse packages available. The Eclipse IDE For Java Developers package is recommended, but any package that includes the Eclipse Java Development Tools (JDT) and the Graphical Editing Framework (GEF) will work. Note that Eclipse Classic does not include GEF and will not work. Download Eclipse packages from:
NOTE: Eclipse packages are available in 32-bit and 64-bit versions. Download the version that matches your Java installation: if you installed 32-bit Java, install the 32-bit version of Eclipse. 64-bit Eclipse requires 64-bit Java.
For Mac OS/X, if your Mac has a 32-bit processor, download the 32-bit version of Eclipse. If your Mac has a 64-bit processor, download the 64-bit version of Eclipse. To determine your processor type, see the following link:
To install Eclipse, simply unpack the Eclipse archive in the directory where you want to put it. When you extract the archive, an eclipse subdirectory is created that holds all of the subdirectories and files that make up the Eclipse package.
For example, if you extract the archive in the root directory of the C drive on Windows (C:\) the Eclipse directory will be C:\eclipse. Make a note of the directory where Eclipse is installed.
NOTE: On Windows, the use of a third-party archive utility, such as WinZip, WinRar, or JustZIPIt is recommended when extracting the archive.
After installing, launch Eclipse and make sure that the Eclipse IDE launches sucessfully. If Eclipse does not launch, check the following FAQ list:
wiki.eclipse.org/FAQ_I_unzipped_Eclipse,_but_it_won’t_start._Why%3F
Configure Eclipse Memory Use
The default memory settings for Eclipse may cause issues, especially if you install additional plugins besides the Particle Platform. To avoid problems, increase the amount of memory allocated for the Java virtual machine when running eclipse.
1. Open the folder where you installed Eclipse and open eclipse.ini in a text editor.
2. Add the following lines at the end of the file, after the -vmargs line:
-XX:PermSize=128m -XX:MaxPermSize=128m -Xms256m -Xmx512m
If there are other flags after -vmargs, remove any existing -XX:PermSize, -XX:MaxPermSize, -Xms or -Xmx flags, which might conflict with these settings.
These settings allocate a maximum of 512 MB for heap memory and 128 MB for permanent generation space—the space allocated for class definitions and other items that are never garbage collected. If memory is limited on your system, you can try lowering the maximum heap size to 256 MB
by changing the last line to:
-Xmx256m
The other lines should stay the same to prevent issues.
Uninstall Any Existing Particle SDK Installation
If you have a previous version of the Particle Platform installed, remove it before installing the new release. After uninstalling the SDK, you must start Eclipse to clear its cache.
To uninstall the beta on Windows
1. Click Start > Particle SDK > Uninstall Particle SDK.
2. Click Yes to confirm the action. When the uninstall process finishes, click OK.
To uninstall the beta on Mac OS X
1. Open the folder where you installed the Particle SDK.
2. Double-click uninstall.
3. Click Yes to confirm the action. When the uninstall process finishes, click OK.
Clear the Eclipse Plugin Cache
Eclipse caches information about installed plugins. To ensure that the cache is cleared, perform the following steps.
1. Start Eclipse by navigating to the folder where you installed Eclipse and double-clicking on the Eclipse icon.
2. If you see a prompt to select a workspace, select the workspace where you were working on Particle projects.
3. When Eclipse finishes launching, click File >Exit.
You are ready to reinstall the Particle Platform.
Install or Upgrade the Particle SDK
To install the Particle Platform, download and run the Particle SDK installer. To avoid problems, you should uninstall the previous version first, as described above.
1. If you don’t already have the Particle SDK installer, download it from one of the following links:
On Mac OS X, the installer is stored as a compressed zip file to save space. Double-click on the zip file to extract the installer.
2. Close Eclipse if it is running.
3. Double-click on the installer.
4. Choose the version of the JDK you want to use with the Particle Platform.
5. Click Next.
6. Select I accept the agreement and click Next to accept the license agreement.
7. Choose where to install the SDK and Click Next.
8. Specify the folder where you installed Eclipse and click Next.
9. Specify the folder where you installed Python and click Next.
Note that the installer expects this path to be a real folder that contains the Python executable (not a shortcut, alias or symbolic link). On Mac OS X, you’ll need to enter the full path to the Python 2.6 installation folder. If you installed Python using Homebrew, the default path is:
/usr/local/Cellar/python26/<version>
Where <version> is the three-digit version number (for example, 2.6.6).
If you installed Python using MacPorts, the path is typically:
/opt/local/Library/Frameworks/Python.framework/Versions/2.6
10. The next page presents information about the Particle Usage Data Collector. You can choose to enable or disable usage data collection. You can change this setting later in the preferences dialog. Click Next.
11. Click Next to start the installation. When the installation completes, click Next to continue.
12. Click Finish to close the installer.
Get Started With The Particle Platform
To use the Particle Platform, you’ll need to start Eclipse. To start Eclipse, open the Eclipse folder and double-click on eclipse (OS X) or eclipse.exe (Windows). On Windows, you can also click Start > Particle SDK > Start Eclipse.
See Getting Started with the Particle Platform for a tutorial that will lead you through creating your first Particle application.
You can also find the Particle Platform documentation through the Eclipse help system:
- Click Help >Help Contents then click Particle Platform Help.
To see context-sensitive help for any of the Particle IDE editors and views, click on the question mark or press F1.
To get help from the Particle Code team and other developers, visit the Particle Platform discussion forums:
Sample Code
If you’d prefer to jump straight into sample code, you can find a full set of code samples in the Particle installation folder. Each sample project is a separate Eclipse project that you can import directly into your workspace and run.
Import a Sample Project
1. Click File > Import.
2. Click the triangle next to General to expand the General group, or double-click General.
3. Click Import Existing Projects Into Workspace, and click Next.
4. Click the Browse button next to Select root directory and select the following folder:
ParticleSDKFolder/Samples
Where ParticleSDKFolder is the folder in which you installed the Particle Platform, such as C:\ParticleSDK or /Applications/ParticleSDK.
After you choose a directory, the sample projects should show up in the Projects list.
5. Select the projects you want to import.
If you’d prefer to work on copies of the sample projects, check the Copy projects into workspace checkbox.
6. Click Finish
