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 at http://localhost:3000 and see the Pico.

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

Lines 11-16: 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 18-21: 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 name, or type, hello.

Installing Your Ruleset

A recommended workflow for writing KRL is found in KRL Programming Workflow. 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, and installs the compiled code inside the pico.

Installing a ruleset in a pico enables the pico-engine to evaluate 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 indicated and click on that “Install” button. You can ignore the “Config” box for now, but it will be used in subsequent lessons.

Clicking on the "Install" 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 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. 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. We 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 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 Quickstart, you are prepared to continue with the Events and Queries Lesson

developer

Pico Engine Quickstart