This page will guide you through the steps necessary to obtain and operate your own pico engine.

Learning Objectives

After completing this Quickstart lesson, you will:

understand important concepts about programming in KRL including ruleset structure
know how to install and operate the node pico engine
know how to use the "My Picos" page to register a ruleset
know how to install a ruleset to a pico
become familiar with using the "My Picos" page to work with your picos

Concepts

Getting started with KRL can be a big leap because there are so many things that are different about programming in KRL:

KRL is a rule-based language.
KRL primarily follows an event-based programming model.
KRL programs execute with a cloud-based model; there is no way to execute them from the command line.
KRL programs are loaded from the cloud using HTTP.
KRL programs execute in a system where identity is pervasive; all events are raised on behalf of a specific entity.
KRL programs have built-in, entity-specific persistent storage; there is no need for external databases.

The result of these properties is a programming model that more closely resembles programming cloud-based persistent objects than anything else. We call these persistent computational objects "picos".

KRL is executed by your instance of the node pico engine, an open-source, cloud-based rule processing system. All of the properties listed above are present in any KRE system.

To be executed, a ruleset must be

available via HTTP and identified by a URL
The URL must be registered with one or more pico engines where it will be known by a ruleset ID or RID
The RID must be installed in one or more picos
The pico must receive a request via the Sky Cloud API or the Sky Event API

Prerequisites

To complete the Quickstart, you will need

An editor
Git on your machine
A pico engine

Install and run the pico-engine

Prerequisite: you will need to install node (also known as Node.js) on your machine. Be sure that you are installing at least version 4. The installation includes npm, the node package manager, which you will use to install the pico engine. (Node.js is a trademark of Joyent, Inc. and is used with its permission. Picolabs is not endorsed by or affiliated with Joyent.)

Once you have npm and node on your machine, open a command line window and issue these two commands, which will install and start the node pico engine.

$ npm install -g pico-engine
$ pico-engine
http://localhost:8080

The node pico engine will spend some time initializing internal data structures before it starts its web server. After doing this, it will start a web server on port 8080.

Note that the web server displays the URL of its document root, ex. "http://localhost:8080" and then continues to run. As we will see later, messages will be logged to this console, so it is best not to close this command line window.

The Primary, or Owner, Pico

During the pico engine initialization, it creates a primary pico, naming it "Owner Pico" and then registers four rulesets and installs two of them in the owner pico. These are the minimum required for running the pico and the developer UI. You can visit the developer UI, "My Picos", at the address on which the pico engine is listening.

Your owner pico is represented by a rounded rectangle, which is placed on a canvas, allowing you to change its placement. Keep this tab open for use in registering and installing your ruleset, below.

Writing KRL

Overall Structure of a KRL Ruleset

A first ruleset, in a file named hello_world.krl:

ruleset hello_world {
  meta {
    name "Hello World"
    description <<
A first ruleset for the Quickstart
>>
    author "Phil Windley"
    logging on
    shares hello
  }
 
  global {
    hello = function(obj) {
      msg = "Hello " + obj;
      msg
    }
  }
 
  rule hello_world {
    select when echo hello
    send_directive("say") with
      something = "Hello World"
  }
 
}

The following describes parts of the ruleset shown above:

Line 1: A ruleset starts with the ruleset keyword, the ruleset identifier or RID, and a curly brace. In this case, the RID is hello_world.

Lines 2-10: A ruleset usually contains a meta block giving information about the ruleset. This information includes information like the ruleset name and author, as well as pragmas that affect the ruleset's behavior. For example, this ruleset has a shares pragma saying which global functions are shared with the outside world (including other rulesets).

Lines 12-17: A ruleset usually contains a global block which globally binds values to names, some of which may be shared.In this case, the name hello is bound to a function value and is shared.

Lines 19-23: A ruleset usually contains one or more rules. In this case there is one rule named hello_world which will be watching for events with domain echo and type hello.

Registering and Installing Your Ruleset

A recommended workflow for writing KRL is found in KRL Programming Workflow. Please read and set up a workflow using your favorite editor and Git.

Registering a ruleset means to make it available to the pico engine, which compiles the KRL source code into JavaScript and caches this as a node module.

Installing a ruleset to a pico is properly a user function, but as a developer, you are functioning in both user and developer capacities.

View your Owner Pico by visiting the "My Picos" page (linked from the "Pico Bootstrap" page), as shown above.

Single click on the rounded rectangle which represents your Owner Pico. It opens up, giving you access to information about it.

The "About" tab will be used in subsequent lessons.

Now, click on the "Rulesets" tab. Enter the URL to the KRL source code in the box beside the button "install ruleset from URL" and click on that button.

Clicking on the "install ruleset from URL" will cause the pico engine to get your ruleset using an HTTP GET, compile it, and register it.

If you're using something like GitHub to host your rulesets, be sure that you supply the "raw" URL. The raw URL returns the file without any page chrome. For example, this is a raw and cooked example of the same ruleset. If you're hosting your rulesets on Amazon S3, be sure the URL is public and can be retrieved using a browser.

Finally, the ruleset will be installed in this pico, as you can see when the page refreshes.

Notice that you are allowed to delete from the pico any ruleset that you install.

Next Steps

Having completed this quickstart, you should continue with Events and Queries Lesson

Pico Engine Quickstart