gistfile1.txt

<ng-include src="'helium/views/header.html'"></ng-include>

<div class="container">
	<div class="row">
		<div class="col-md-10 col-md-offset-1" style="margin-bottom: 70px;">
			<div class="">
				<div class="">
					<h2>Helium Alpha</h2>

					<p>Welcome to the Helium Alpha. You're one of the brave and privileged few who are helping us refine our hardware and software. We are in your debt. Thank you. </p>

					<h2>If You Get In Trouble</h2>

					<p>First things first. If you're in need of assistance at any point, the entire Helium team is here to help. </p>

					<ol>
						<li>We've got a <a href="http://forum.helium.co">community forum set up</a> for questions or topics you want to discuss. You can expect us to be very responsive here. Please tag your issues as <code>alpha</code>. There's also a <a href="http://forum.helium.co/t/current-alpha-limitations/11">Current Alpha Limiations doc</a> that you should read before you get going. </li>
						<li>If you prefer email, you can use <code>alpha@helium.co</code> to send questions and comments to the team.</li>
						<li>If all else fails, call Mark directly: 413.335.2332</li>
					</ol>

					<h2>The Helium Console</h2>

					<p>This is the Helium Console. (Call it a "Web UI" if you want. We won't mind.) The Console is where you'll handle all device management as well as various other tasks related to devices and the data they generate.  (In the future we'll have a Helium CLI that does some or all of what the Console does, but this is the only interface for the moment.)</p>

					<p>This short guide will introduce you to all the pieces of the Helium Console. When finished you'll be on your way to programming your Arduiun UNOs and generating data from your army..... </p>

					<ul>
						<li>Devices </li>
						<li>APIs</li>
						<li>Endpoints and Actions</li>
						<li>Action Sets </li>
					</ul>

					<h3>Devices and Logs</h3>

					<p>Every device you own is registered via the Helium Console. We identify them via their unique MAC address. (If you're using one of our Arduino UNO shields, the MAC address will be printed on the antennea.) </p>

					<p>Head over to the <a href="http://alpha.helium.io/#/devices">Devices interface</a> and take a look. Once you've entered a name and the MAC Address and click "Save" this will be tied to your account. You'll also notice we provide device-level logs. These will come in handy as you start to watch data flow in and out of your sensors. </p>

					<p><img src="/public/images/docs/newdevicewithlogs.png" alt="Screenshot 1" title="" /></p>

					<p>A complete view of the device logs are available via the <a href="http://alpha.helium.io/#/logs">Logs interface</a>.</p>

					<p>And in case it wasn't obvious, there is no limit to the number of devices you can manage via the Console. We expect your applications to consist of thousands of devices. We're also planning to provide an interface for bulk registration of devices, too, so when you're bringing a lot online at the same time it won't require manual creation. </p>

					<h3>APIs</h3>

					<p>Helium is an efficient pipe for you device and sensor data. We're not a cloud, meaning we don't intend to store (lock up) your data. Instead, we provide the infrastructure that enables you to pass data from your devices to your applications (and visa versa). This happens via APIs. </p>

					<p>Let's say you want each of your devices to send payment charge data to Stripe. To do this you would create a Stripe API. (We're going to use Stripe for a few more examples so keep this fresh in your mind.) </p>

					<p>When you go the <a href="http://alpha.helium.io/#/apis">API tab</a>, you'll see a button that says "Add a new API." Click it and it'll ask you for three pieces of information: Name, Domain, and Visibilty. Keeping with our Stripe example, here is what you would enter:</p>

					<ul>
						<li><strong>Name</strong> = <code>Stripe</code>            </li>
						<li><strong>Domain</strong> = <code>https://api.stripe.com/</code> </li>
						<li><strong>Visibility</strong> = <code>Public</code>  </li>
					</ul>

					<p>If you wanted to write data to one of your private APIs, it would look something like this. </p>

					<ul>
						<li><strong>Name</strong> = <code>Super Secret API</code>            </li>
						<li><strong>Domain</strong> = <code>https://api.myapp.com/</code> </li>
						<li><strong>Visibility</strong> = <code>Private</code>  </li>
					</ul>

					<p>There's no limit to the numbmer of APIs you can have, and it's even possible to send the same data to many APIs in parallel with just a single request. We'll talk about how to do this in a few minutes. </p>

					<h3>Endpoints and Actions</h3>

					<p>After creating an API you'll be prompted to add an Endpoint. If you used the Stripe example from above, it'll look like this:</p>

					<p><img src="/public/images/docs/stripeapinoendpoint.png" alt="Screenshot 2" title="" /></p>

					<p>Endpoints are the specific parts of a given API you wish to call with a piece of data fom a device. Helium requires the following information to register Endpoints in the system: Name, Path, Body Template, and Method. If we wanted to create an Endpoint used to charge cards via Stripe, here's what that would look like:</p>

					<ul>
						<li><strong>Name</strong> = <code>Charge a Card in Stripe</code></li>
						<li><strong>Path</strong> =  <code>/v1/charges</code></li>
						<li><strong>Body Template</strong> =  <code ng-non-bindable>amount={{.a}}&amp;currency=usd&amp;card[number]={{.n}}&amp;card[exp_month]={{.m}}&amp;card[exp_year]]={{.y}}</code></li>
						<li><strong>Method</strong> = <code>POST</code></li>
					</ul>

					<p>(You'll notice there are some bracketed variables in the <code>body template</code> section. These will be supplied with the relevant data coming off of your Arduino.)</p>

					<p>After you've added an Endpoint to an API, you can add more. Perhaps you want to make the <code>Refund a Charge</code> end point available, too? <em>To make this Endpoint truly useful, however, you'll want to add an Action to it</em>. Take a look at this:</p>

					<p><img src="/public/images/docs/modaltocreateendpoint.png" alt="Screenshot 3" title="" /></p>

					<p>That small arrow in the upper right gives you the option to do several things, one of which is "Create an Action." Click it and you'll see this beautiful modal:</p>

					<p><img src="/public/images/docs/actionaddviamodal.png" alt="Screenshot 4" title="" /></p>

					<p>Once you've created an API and an associated Endpoint, you can extend it with an Action. To create the Action, select the Action Set to which it belongs (it'll be attached to the default Action Set if you haven't created any yet) and give it a unique name. Actions are also identified by a two byte key (which we'll assign for you if you choose not to specificy it).</p>

					<p>Actions specify the full parameters of an API call, and (currently) give you the ability to supply inputs for Username and Password (using Basic Auth), Path Variables and Headers. This information, along with the body template you supplied in the Endpoint, will let you make a full API request using data produced by your device. Pretty slick. </p>

					<h3>Action Sets</h3>

					<p>Actions Sets are powerful. They let you group functionality contained in your Actions. Above we mentioned that you could send data to various APIs simulaneously in the course of the same request. Let's say that, after you charge a given card (made possible by our Stripe API) you want send an SMS message to that card holder congratulating them on their purchase. You can use Twilio for this. After you've added the Twilio API, the relevant endpoint (Sending SMS), and the Action, you could build an Action Set composed of the two Actions you need. Here's what it would look like in the Console:</p>

					<p><img src="/public/images/docs/stripeandtwilio.png" alt="Screenshot 5" title="" /></p>

					<p>Now all you need to do is to tell your Arduino to call this Action Set once it has capture the relevant data. Let's do that.</p>

					<h3>API Keys, Action Set Keys, and Action Keys</h3>

					<p>After you've built the necessary APIs, Endpoints, and Actions, it's time to program your Arduino UNO to send data using them. This is done by including a three keys information in the your code that are generated and viewable in the Helium Console. Take a look at this example Action Set:</p>

					<p><img src="/public/images/docs/completeactionset.png" alt="Screenshot 6" title="" /></p>

					<p>In the above Action Set Screen shot there are a few things to take note of:</p>

					<ul>
						<li><strong>API Key</strong> - This is a unique ID that identifies the API you've created. The Console will assign this key for you but you can also specify it if you wish. </li>
						<li><strong>Action Set Key</strong> - THe unique ID for the Action Set Key. Again, we create this for you unless you change it. </li>
						<li><strong>Action Key</strong> - Another unique ID. One this to note here is that these keys are unique to the Action Set (meaning if created the same Action as part of another Action Set, Helium treat them as two different Actions.) </li>
					</ul>

					<p>These keys are significant primarily because they are how you'll reference and execute this functionality in your Arduino code. As you'll read in the <a href="http://john.skynet.io:4567/#helium-arduino-library">Ardunio Docs</a>, you'll be creating <code>DataPack</code> objects that reference your keys. The format looks like this:</p>

					<p><code>
						dp DataPack(api, actionset, action, 3)
					</code></p>

					<p>Using the example from our screenshot, here's what the code to call this API and its related pieces would look like:</p>

					<p><code>
						dp DataPack(240, 213, 142, 3)
					</code></p>

					<h3>Programming Your Arduino UNO</h3>

					<p>We've written <a href="http://arduino.docs.helium.co/">complete docs for our Arduino Library</a>. Head over there to get started. </p>
				</div> <!-- panel-body -->
			</div> <!-- panel-default -->
		</div> <!-- col-md-12 -->
	</div> <!-- row -->
</div> <!-- container -->