...

Prerequisites

• complete the Pico-Engine NEXT Quickstart

• have the hello_world ruleset from the Quickstart installed in a pico

• have installed Postman, or some other HTTP app.

...

Video Tutorial

...

...

Pico as an

...

internet citizen

A pico (quoting from Rebuilding KRL):

...

Picos respond to events and queries using two different URL schemesformats. Events are sent to a pico using the Sky Event API. Queries are made using the Sky Cloud API. 

...

Here is a sample URL that sends an event to a pico like the one you created in the Pico-Engine NEXT Quickstart:

http://localhost:3000/sky/event/ckcvuri6r0017conl4siq0q3r/1556/echo/hello

Breaking this URL into components:

• "http://" identifies HTTP as the protocol

• "localhost:3000" is the domain name and port of the pico engine which hosts the pico

• "sky/event" identifies this as an event for the pico

• "ckcvuri6r0017conl4siq0q3r" is one of the pico's event channel identifiers (ECI) (yours will be different)

• "1556" is an arbitrary string which serves as an event identifier (EID) and correlation ID. (useful when looking at logs)

• "echo" identifies the domain of the event

• "hello" identifies the type of the event

queries

Here is a sample URL that sends a query to a pico:

...

This URL shares some components with the URL above for an event. The new components are:

• "sky/cloud" identifies this as a query for the pico

• "ckcvuri6r0017conl4siq0q3r" is one of the pico's event channel identifier or ECIidentifiers (ECI) (yours will be different)

• "hello_world" is the ruleset identifier or RID

• "hello" is the name of a shared function from that ruleset

• "obj" is the name of an argument that the function expects

• "Bob" is the value for that argument

Create a Channel

As you can see in the URLs for events and queries, channels are the way in which a pico can be identified by the pico engine.

...

Since a pico is a first-class Internet internet citizen, there are many ways in which you can send it an event. We will look at two of these three ways:

...

When you develop a ruleset, you may choose to use the "Testing" tab of the developer UI which can provide a simple UI for your eventthe events and queries of the ruleset. The "Testing" tab works by querying your ruleset to see if it shares the name __testing and if it does, it parses the structure that __testing points to and builds simple forms using a map named __testing which is created automatically by the compiler when the ruleset is compiled. The tab builds a simple form to test each of the queries and events which the structure defines. The __testing structure is created automatically map defines (again, as generated by the compiler).

This __testing name can be may also be shared, so you and if you want to do this you can add it to the "shares" entry in the "meta" block of the ruleset. The "shares" keyword is followed by a comma-separated list of names defined in the globals section which we wish to use outside of the ruleset. Any names not mentioned in "shares" are for the private use of the the ruleset and are not exposed outside the ruleset. Edit the "meta" block of your ruleset to look like this:

...

Be sure to validate your source code, using one of the techniques in Developer Tips for Pico Engine to ensure that you have introduced no syntax errors into your ruleset. Once you get the "ok", go ahead and push your changes and flush the ruleset in your pico. (Review the Pico-Engine NEXT Quickstart page if necessary)

Click on the "Testing" tab of the developer UI. Choose the "hello_world" channel from the ECI dropdown. Notice under your ruleset identifier that there are three forms, one for each of the shared functions and the event that you defined in your ruleset.

...

...

In the next example, the name __testing is not shared, so there is no button for it in the Testing tab.

Notice the button "echo/hello", representing this event for your ruleset named "hello_world". Click on this button to send the event.

...

Notice the directive returned by the event.

3. Using postman

You can enter the event URL in postman, and click the Send button. Note the result below:

...

Using logs

Look at the console from which you started your pico engine.

You should see entries like these:

{"level":50,"time":"2020-07-21T12:42:00.593Z","picoId":"ckc...",...,"event":{"eci":"ckc...","domain":"echo","name":"hello","data":...
{"level":50,"time":"2020-07-21T12:42:00.595Z","picoId":"ckc...","txnId":"ckc...","msg":"txnStart"}
{"level":50,"time":"2020-07-21T12:42:00.595Z","picoId":"ckc...",..."msg":"fired"}
{"level":50,"time":"2020-07-21T12:42:00.596Z","picoId":"ckc...","txnId":"ckc...","msg":"txnDone"}

This console log may be useful in debugging events..

3. Using postman

You can enter the event URL in postman, and click the Send button. Note the result below:

...

Send a query through your channel

...

Congratulations! You know how to send queries to a pico, either directly using a URL, or through the "Testing" tab of the UI, or through Postman.

...

Using logs

KRL provides an operator, klog(), which allows us to print information into the logs. It is an operator, rather than a statement, so it is applied to an expression. It prints into the log the message passed to it as an argument, followed by the value of the expression on which it operates. Finally, it returns the value of the expression on which it operates, unchanged. This makes it easy to add to or remove from your KRL code without changing its meaning.

...

Here we see the logging for a query and an event.

Note that since the UI works by sending events and queries to the io.pioclabs.pico-engine-ui ruleset, you’ll also see those events and queries in the output. If anyone is interested in contributing to the React code that implements the UI to filter the logs, it is open source.

Congratulations!

You now know how to send events to, and make queries of, a pico. You have also learned some debugging techniques.

...