Quick Start

Introduction

In this topic, we will build the Zetta version of "Hello, World!". When you finish, you will know how to:

• Create a basic Zetta project
• Start the Zetta server
• Call the Zetta device API

In later tutorials, we'll build out this basic Zetta project with more functionality. 

Install Node.js and npm

You need to have Node.js and NPM (Node Package Manager) installed on your system. If you do not have this software, follow these steps:

Go to the Node.js download site and follow the installation instructions for your system. The download installs both Node.js and NPM.

Verify that the node and npm commands are in your path:

  node -v
    <installed version number>
      
  npm -v
    <installed version number>

Create a Zetta project

1. Create a new directory called hello-zetta.

2. cd to the directory.

3. Execute this command to create a new Node.js project:

   npm init

4. Hit return several times to accept all the defaults. This step creates a package.json file, which contains meta information about the project and its dependencies.

5. Install the zetta Node.js module. The --save option adds zetta to the package.json dependencies list.

   npm install zetta --save

You now have a bare-bones Zetta project containing a node_modules directory and a package.json file. Next, we'll configure the Zetta server.

Configure the Zetta server

Zetta includes an HTTP server that you can run locally as a Zetta hub or deploy to the Cloud. Hub servers and Cloud servers can be linked, providing world-wide Internet access to devices configured with Zetta. For now, we'll set up a simple server and run it locally.

1. Be sure you're in the hello-zetta directory.

2. In a text editor, create a new file called index.js, and copy this code into it:

var zetta = require('zetta');

zetta()
  .name('FirstName LastName')
  .listen(1337, function(){
     console.log('Zetta is running at http://127.0.0.1:1337');
});

3. In your editor, replace 'FirstName LastName' with 'Hello Zetta'.

var zetta = require('zetta');

zetta()
  .name('Hello Zetta')
  .listen(1337, function(){
     console.log('Zetta is running at http://127.0.0.1:1337');
});

4. Save the file.

You now have pretty much the most basic Zetta server hub possible! Let's test it.

Start the server

In the hello-zetta directory, enter this command:

node index.js

You'll see output like the following, indicating that the server is running. Note that the server name appears in the output.

Aug-26-2015 09:05:53 [server] Server (Hello Zetta) Hello Zetta listening on http://127.0.0.1:1337
Zetta is running at http://127.0.0.1:1337

Call the Zetta API

We need to call the server's root URL, which is:

http://127.0.0.1:1337

If you have cURL installed, you can do this:

curl http://127.0.0.1:1337

Or, you can use a REST client like Postman or Advanced REST Client to call the URL. It's a good idea to obtain and begin working with these tools if you intend to develop Zetta applications.

Tip: If you use Chrome, you can install a plugin called JSONView, which formats JSON responses nicely.

The server returns a JSON object that describes the root class of the API. Basically, this response describes the current state of the Zetta API and links to resources provided by the API (we'll explore links in the next section).

At this point, our API doesn't do much, but as we start adding devices to the server, the API will expand to support those devices. 

{
  "class": [
    "root"
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/"
    },
    {
      "title": "Hello, Zetta!",
      "rel": [
        "http://rels.zettajs.io/server"
      ],
      "href": "http://localhost:1337/servers/Hello%20Zetta"
    },
    {
      "rel": [
        "http://rels.zettajs.io/peer-management"
      ],
      "href": "http://localhost:1337/peer-management"
    }
  ],
  "actions": [
    {
      "name": "query-devices",
      "method": "GET",
      "href": "http://localhost:1337/",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "server",
          "type": "text"
        },
        {
          "name": "ql",
          "type": "text"
        }
      ]
    }
  ]
}

Note: The Zetta API conforms to the Siren hypermedia specification. You can read about Siren on the GitHub repository.

Key point: The Zetta API is a built-in, out-of-the-box feature of Zetta. It automatically generates APIs for devices that you add. These APIs can be deployed in the Cloud allowing any authorized user to interact with the devices from anywhere in the world.

Follow the /servers link

If you follow the /servers link (in the links part of the JSON response), it returns the API for the "Hello World" server itself. That is, it's the API for whatever entities and actions are attached to the named server. This is the link an app developer would follow to discover what this instance of Zetta can do. Try hitting this link:

http://localhost:1337/servers/Hello%20Zetta

At this time, no devices are attached to the server; therefore, the entities array is empty. Note, for now, that the API has a query-devices action. In the "Add a Mock Device" tutorial, we'll see how to add a device driver to the server and query for it.

{
  "class": [
    "server"
  ],
  "properties": {
    "name": "Hello Zetta"
  },
  "entities": [],
  "actions": [
    {
      "name": "query-devices",
      "method": "GET",
      "href": "http://localhost:1337/servers/Hello%20Zetta",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "ql",
          "type": "text"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/servers/Hello,%20Zetta!"
    },
    {
      "rel": [
        "http://rels.zettajs.io/metadata"
      ],
      "href": "http://localhost:1337/servers/Hello%20Zetta/meta"
    },
    {
      "rel": [
        "monitor"
      ],
      "href": "ws://localhost:1337/servers/Hello%20Zetta/events?topic=logs"
    }
  ]
}

Summary

Congratulations! You've built a functioning Zetta hub. In the next part of the tutorial, we'll wire up a mock device driver that implements a simple state device (on/off switch). Then, we'll take a look at the API for that device, which lets a client app turn the device on and off.