Learning Objective
After completing this lesson, you will be able to:
- explain how a pico is a first-class Internet citizen
- explain channels and use the "My Picos" page to manage them
- send events and queries to a pico using a browser, the event console, and the "Testing" tab
- use logs
- use the klog() operator
Prerequisites
- complete the Pico Engine Quickstart
- have the
hello_world
ruleset from the Quickstart registered in the pico-engine, and installed in a pico - have installed the event console in Google Chrome
Pico as an Internet citizen
A pico (quoting from Rebuilding KRL):
...
A pico has multiple URL's that can be used to query its state and send it events.
events
Here is a sample URL that sends an event to a pico like the one you created in the Pico Engine Quickstart:
...
- "http://" identifies HTTP as the protocol
- "localhost:8080" is the domain name and port of the pico-engine which hosts the pico
- "sky/event" identifies this as an event for the pico
- "citdel5gz00012aaoo5ucc613" 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:
...
- "sky/cloud" identifies this as a query for the pico
- the event channel identifier or ECI
- "hello_world" is the ruleset identifier or RID
- "hello" is the name of a shared function from that ruleset
- "obj" is the name of the argument that the function expects
- "Bob" is the value for that argument
Create a Channel
As you can see in the URL for events and queries, channels are the way in which a pico can be identified by the pico-engine.
...
Make a note of the event channel identifier (ECI) assigned to your temporary channel. You will be using this "lesson" channel throughout the rest of this lesson.
Sending events through the channel
Since a pico is a first-class Internet citizen, there are many ways in which you can send it an event. We will look at three such ways here:
- Directly using a URL through a client (ex. a browser, or the `curl` command at the command line)
- Using the event console or some other console for RESTful APIs
- Using the "Testing" tab of the UI
1. Directly using a URL
Construct a URL that identifies your Pico by the channel id that you created in the previous section. Remember to replace the channel identifier in the sample URL with the identifier of your "lesson" channel. Also, you may choose your own event identifier (rather than use "5", as we did for this screenshot).
...
Directives allow picos to direct endpoints to react a certain way to an event. Our rule's directive just says hello, but it could be used to do more complex things. Directives allow the program's logic to be placed in the rules, not in the end points. Placing logic in the rules provides loose coupling with easier scaling and maintenance.
2. Using the event console
The Kynetx event console is a Google Chrome application that you can add to your browser to make it easy to send events. You can find it on github and install it into your browser following the instructions. You can then launch it and enter in the host:port of your pico engine, the channel identifier and the event domain and type. You will need to un-check the box beside "Use HTTPS".
...
Notice that the event identifier was chosen by the event console.
3. Using the "Testing" tab
When you develop a ruleset, you may choose to use the "Testing" tab of the "My Picos" page which can provide a simple UI for your event. 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 to test each of the queries and events which the structure defines.
...
Notice in the directive returned by the event that the "Testing" tab uses the event identifier "__testing".
Using logs
Look at the console from which you started your pico-engine.
...
For example, try introducing a typo in the URL for the event, say by spelling "echo" incorrectly as "ecco". In the console log, you will see that the event is received, and the Pico selected (based on its ECI), but you will not see that the event has fired.
Send a query through your channel
Create a URL for your Pico which uses your "lesson" channel identifier. It will look something like
...
Congratulations! You know how to send queries to a pico, either directly using a URL, or through the UI.
More about 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.
...
Code Block |
---|
[DEBUG] { rid: undefined, event: { eci: 'ciu4b6zui0001jfs0nmki6z1y', eid: '5', domain: 'echo', type: 'hello' } } rule selected: hello_world -> hello_world [KLOG] our passed in name: Bob [DEBUG] { rid: 'hello_world', event: { eci: 'citeh9si400022aao04assjxy', eid: '5', domain: 'echo', type: 'hello' } } fired |
Using the "Logging" tab
Click on the "Logging" tab for your pico.
...
Here we see the logging for a query and an event.
Congratulations!
You now know how to send events to, and make queries of, a pico. You have also learned some debugging techniques.
Next, learn about persistence, the "P" of pico, by working through Pico Programming State Lesson: Pico State.
Exercises
Do the following:
- Create a new channel (pick any name and type you like).
- Send an event to your pico using the new channel.
- Do you get the same result? Why or why not?
- Delete the channel.
- Resend the event using the deleted channel.
- What happens? Why?
- Send the event
ecco/hello
to your pico. What do you observe? Why? - Add a new rule that selects on
echo/monkey
and responds with "Hello Monkey" unless an event attribute namedname
is given, in which case it will respond with "Hello " followed by the given name. Hint: use the.defaultsTo()
operator. Use the.klog()
operator to log the value that is used. - Repeat the previous exercise using the ternary conditional instead of the
.defaultsTo()
operator.
...