This page will guide you through the steps necessary to obtain and operate your own Kinetic Rules Engine (KRE).
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
*This section is copied verbatim from Quickstart (the one for the original KRE system)
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
- A Github account
- A pico engine
Install and run the node pico-engine
Prerequisite: you will need to install node (also known as Node.js) on your machine. It includes npm, the node package manager.
$ npm install -g pico-engine $ PORT=8084 pico-engine http://localhost:8084
In the example above, port number 8084 was chosen. By default, if you run the command `pico-engine` without setting the environment variable, port 8080 will be used. The node pico engine will spend some time initializing internal data structures before it starts its web server.
When you first run the node pico-engine, it does some initialization work, which may take some time. After doing this, it starts a web server on the port you selected, if any, or on port 8080.
Note that the web server displays the URL of its document root, ex. "http://localhost:8084" and then continues to run. As we will see later, messages will be logged to this console.
Create a primary, or owner pico
During the pico engine initialization, it creates a primary pico, naming it "Owner Pico" and then registers and installs two rulesets. These are the minimum required for running the pico and the developer UI. You can visit the developer UI at the address on which the pico engine is listening. From there you will have a link to the main developer UI page, "My Picos":
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
Do the following:
- Create a
git
repo for your KRL rulesets and put it on Github. You can create a different repo for each ruleset if you like or create one repo and put multiple rulesets in it. Create a file in your ruleset repo called
hello_world.krl
and put the code below into it.- Validate (parse) your ruleset using one of the methods in Developer Tips for Pico Engine.
- Check your validated ruleset into Github.
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" } }
Overall Structure of a KRL Ruleset
A ruleset is enclosed by the "ruleset" keyword, the ruleset identifier or RID, and curly braces, as shown above in lines 1 and 25. In this case, the RID is "hello_world".
A ruleset usually contains a "meta" block giving information about the ruleset and any names which it "shares" with the outside world (including other rulesets). Lines 2-10.
A ruleset usually contains a "global" block which binds values to names, some of which may be shared. Lines 12-17. In this case, the name "hello" is bound to a function value and is shared.
A ruleset usually contains one or more rules. Lines 19-23. 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
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 send an event to your pico. This event is captured by rules in the "io.picolabs.pico" ruleset, which will cause the pico engine to get your ruleset from the Internet, compile it, and register it.
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 Lesson 1. Events and Queries