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

1. An editor
2. Git on your machine
3. 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

...

Pre-requisites

The pico-engine is implemented in Node.js and consists of packages managed by npm, so you will need to install both node and npm on your machine. Some suggestions for this are located in the pico-engine code repository and in “npm Docs”. Once you have npm installed on your machine, continue with the installation of the pico-engine.

You may find these topics of interest once you’ve got your engine running.

Installation Video

Installation

Normally, this will be a single command, shown here:

npm install -g pico-engine

To do this you will need to first install node. You may need to upgrade your version of node to the latest version if it is already installed.

If you experience permission problems, consult this page of the npm Docs. Depending on your OS, you may need to install as root. There is also a troubleshooting section in the pico-engine code repository.

Operation

Running the pico-engine is also a single command:

pico-engine

Now, go to your browser and visit this page:

http://localhost:3000

Developer Interface

The pico-engine starts with a primary, or root pico.  This Pico is set up with the minimum required rulesets for running a pico in the developer UI. You can visit the developer UI , "My Picos", at the address on which the pico engine is listening.

Image Removed

Your owner at http://localhost:3000 and see the Pico.

...

The root pico is represented by a rounded rectangle , which is placed on a canvas, allowing you to change its size and placement. Keep this tab browser 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:

...

as we will use it later to install a ruleset. We will start with a simple ruleset designed to echo a “Hello World” message, described in the next section.

When you single click on the name of the Pico, its rectangle opens up, giving you access to information about it, with a tabbed interface.

...

The "About" tab will be used in subsequent lessons. For now, notice that the pico is identified by a unique identifier, called an event channel identifier (which also appears as part of the browser’s location bar), and that it has no children. You can change the pico’s name and color from this tab.

Hello World KRL Ruleset

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

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 the ruleset keyword keyword, followed by the ruleset identifier or RID, and a curly brace. In this case, the RID is hello_world. The body of a ruleset is contained within the curly brackets opening at line 1 and closing at line 24. By convention, this ruleset will be stored in a file named hello_world.krl (the RID followed by a .krl file extension).

Lines 2-109: A  A ruleset usually contains a a meta block  block giving information about the ruleset. This information includes information data like the ruleset ruleset name and  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 1211-1716: A  A ruleset usually contains a a global block  block which globally binds values to names, some of which may be shared. In this case, the name name hello is  is bound to a function value and is shared.

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

...

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 This example uses the local filesystem of the author to host KRL source code. 

When you install a ruleset, the pico-engine fetches the KRL source code from the URL you provide, parses and compiles the KRL source code into JavaScript and caches this as a node module, and installs the compiled code inside the pico.

Installing a ruleset in a pico enables the pico-engine 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.

Image Removed

The "About" tab will be used in subsequent lessonsevaluate selected rules for that pico when corresponding events are raised to that pico. All of the computation done by a pico, and all of the data that it stores, is specified by the rulesets which are installed in the pico.

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

Image Removed

You can ignore the “Config” box for now, but it will be used in subsequent lessons.

Clicking on the "install ruleset from URLInstall" button will cause the pico-engine to get your ruleset using an HTTP GET, compile it, and register it with the engine and install it in this pico. 

...

Your URL will be different from the one shown here.

If you're using using something like GitHub to host your rulesets, be sure that you supply the "raw" URL. The raw URL returns 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. Besides being able to do everything the first three rulesets can do, this pico can now do hello_world kinds of things. We will see more about this in future lessons.

...

One of the rulesets is at version “0.0.0”. You can ignore the version information for now, but this will be discussed in subsequent lessons. Your ruleset doesn’t have a version, and so is considered to be a “draft” at this point. This allows you to edit it and work with it more easily. Image RemovedWe will refine the hello_world ruleset in subsequent lessons.

Clicking on the checkbox beside your ruleset’s RID reveals more information about it.

...

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

After you have modified the source code (remember that it is stored at the location indicated (in this case in your local filesystem)) you can hit the “flush” button to have the engine update the installed ruleset from your changes.

The line labeled “Hash” indicates the engine’s identifier for the current version of your ruleset source code. When you edit your source code and flush the changes, this identifier will change.

You now own a pico, with a ruleset you coded installed in it.

Next Steps

Having completed this quickstartQuickstart, you should are prepared to continue with the Events and Queries Lesson

...