Pico URLs

Pico URLs are Python objects that hold information used to construct a URL targeting a Pico endpoint. This information can include the event channel identifier (ECI), ruleset id, event id, event domain, event type, and ruleset function name.

Static vs. Dynamic

The picosapi URL objects can be created as either static of dynamic. By default, the URL objects are created as dynamic, meaning that if the host and port values in the picosapi configuration are changed, the URL object's host and port values will also change.

Optionally, you can specify that the URL object be created as static. This means that even if somewhere else in the script you change the picosapi configuration host and port values, statically-created URL object's host and port values will not change.

Why dynamic URLs?

Easy configuration. Using dynamic URLs means that even if you change the host or port that the pico engine is running on, you don't have to change the host and port values for every URL object in your script. The module takes care of that for you.

Event URL

Event URLs target the /sky/event API and can be constructed using the picosapi.event_url() function. This function has four required parameters:

• eci - the event channel identifier (ECI) of the Pico to raise an event on
• event_name - the name/id of the event to raise
• event_domain - the domain of the event
• event_type - the type of the event

There are also additional optional arguments:

• static (default False) - if True, allows the generated URL object's host and port to be modified
• host (default None) - alternately specified host IP address
• port (default None) - alternately specified host port

---

NOTE

The picos.event_url() function returns an EventURL object that has the following publicly available members:

• eci - the event channel identifier
• name - the event name or id
• domain - the event domain
• type - the event type
• host - the target host
• port - the target port

In most use cases you will not need to modify the generated URL member values, but in case you do (such as programatically changing the eci when targetting multiple picos you want to raise the same event on), they are available.

---

Below is an example of creating and using an Event URL when adding a new Wovyn temperature sensor pico to a sensor manager pico:

import picosapi as picos
...
add_sensor_url = picos.event_url(my_pico_eci, "add-sensor", 
                                 "sensor", "new_sensor")
ok, response = picos.post(add_sensor_url, data={"sensor_id": i})

API URL

API URLs target the /sky/cloud API and can be constructed using the picosapi.api_url() function. This function has three required parameters:

• eci - the event channel identifier (ECI) of the Pico sharing the API function
• ruleset_id - the id of the ruleset the API function belongs to on the Pico
• api_function - the name of the function in the ruleset to call

There are also additional optional arguments:

• static (default False) - if True, allows the generated URL object's host and port to be modified
• host (default None) - alternately specified host IP address
• port (default None) - alternately specified host port

---

NOTE

The picos.api_url() function returns an ApiURL object that has the following publicly available members:

• eci - the event channel identifier
• ruleset_id - the name/id of the ruleset being targeted
• function - the name of the endpoint function exposed by the ruleset
• host - the target host
• port - the target port

In most use cases you will not need to modify the generated URL member values, but in case you do (such as programatically changing the eci when targetting multiple picos you want to raise the same event on), they are available.

---

Below is an example of creating and using an API URL when querying information about Wovyn temperature sensors registered with a sensor manager pico:

import picosapi as picos
...
temperature_url = picos.api_url(my_pico_eci, "manage_sensors", 
                                "temperatures")
ok, response = picos.get(temperature_url)