Learning Objectives

After completing this Quickstart lesson, you will be able to:

install and operate the node pico engine
manage picos with the pico engine developer UI.
understand basic KRL ruleset structure
register a ruleset with a pico engine
install a ruleset in a pico

Getting started with KRL can be a big leap, not all topics can be covered here, so please refer to rulesets and other documentation as needed.

Prerequisites

To complete the Quickstart, you will need

code editor
git (optional)
node.js version 6 or greater with npm

Install and run the pico-engine

Use npm to install and start the node pico engine.

$ npm install -g pico-engine
$ pico-engine

The node pico engine will spend some time initializing internal data structures before it starts the developer UI at http://localhost:8080.

Note that the web server displays the URL of its document root, ex. "http://localhost:8080" and then continues to run. Messages are logged to this console, so do not close the command window.

The Primary, or Owner, Pico

The pico engine starts with a primary pico named "Owner Pico". The Owner Pico is setup with the minimum required rulesets for running the pico and the developer UI. You can visit the developer UI at http://localhost:8080 and see the Owner Pico.

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

Hello World KRL Ruleset

The hello world ruleset is an example of basic KRL ruleset structure.

hellow_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", {"something": "Hello World"})
  }
 
}

The following describes parts of the ruleset shown above:

Line 1: A ruleset starts with the ruleset keyword, followed by the ruleset identifier or RID. In this case, the RID is hello_world. The body of a ruleset is contained within curly brackets.

Lines 2-10: A ruleset usually contains a meta block giving information about the ruleset. This information includes data 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-22: 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. This example uses github as a host.

When you Register a ruleset, the pico engine parses and compiles the KRL source code and makes the uniqe ruleset ID avalible to install inside picos.

Installing a ruleset inside a pico enables the pico engine to evaluate each rule on that pico when corresponding events are raised to that pico.

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 are prepared to continue with Events and Queries Lesson

Pico Engine Quickstart