Picos API

Notes

For all functions, enter the parameters in the order listed.
Italicized parameters are optional.
Received Events are events of the "wrangler" domain that Wrangler will respond to
Raised Events are events that can be selected on within any ruleset in the pico when they occur
Sent Events are events that the pico will send elsewhere as a result of triggering a Wrangler event.

Functions

children

Returns an array of the children of the pico. Has optional parameter "name" which returns just the attributes for the children with the specific name if they exist, otherwise it returns attributes on every child if not provided. Has also optional parameter "allowRogue" which is by default true. Will not return child picos that are currently being deleted.

Parameters

Parameter	Datatype	Description
name	String	Name of the pico(s) to search for
allowRogue	Boolean	Determines whether the children call will return picos that do not have Wrangler installed on them. If this is set to false children() will only return picos that Wrangler is guaranteed to be installed on.

Returns

An array containing a map for each returned pico. Each map contains:

parent_eci: The ECI from the pico to the respective child. Should be used for parent-child interaction.

name: The child pico's name

id: The id of the child pico

eci: The main Wrangler ECI for the child pico

Example

children = wrangler:children()
/*
[
  {
    "parent_eci": "CyrmdG4PkiVYRUo2K69k2E",
    "name": "Section CS462-1 Pico",
    "id": "cjh6pbzun005zvde06bwy2pci",
    "eci": "JfcEBxEK5WDKA69Bvach4Y"
  },
  {
    "parent_eci": "Tg5ULPBYByJjsEoKpfsbQ2",
    "name": "Section CS462-2 Pico",
    "id": "cjh6pc28r0067vde04qd23t6o",
    "eci": "56S414r4Uq4kGx6Xi1qmSs"
	"rogue": true
  }
]
*/

childrenWithWrangler = children(null, false)
/*
[
  {
    "parent_eci": "CyrmdG4PkiVYRUo2K69k2E",
    "name": "Section CS462-1 Pico",
    "id": "cjh6pbzun005zvde06bwy2pci",
    "eci": "JfcEBxEK5WDKA69Bvach4Y"
  }
]
*/

childrenNamedRefused = children("refused")
/*
[
	{
		"parent_eci":"5ehT3zigTKhHuHL571dCF5",
		"name":"refused",
		"id":"cjxf0yqiz000o0jbz4kbrgczt",
		"eci":"TR4zpDwpKtuYAbsmBG7Wd7"
	},
	{
		"parent_eci":"8sd1pvKqy54RmdY35bpRvM",
		"name":"refused",
		"id":"cjxf1dhp300150jbz3r5v3x2f",
		"eci":"RGFe5aVgBTG4w2ix8fw52V"
	}
]
*/

myself

Returns a map giving basic meta information about the pico. This information includes the pico's ID, Wrangler ECI, and name.

Returns

A map giving basic information about a pico with the following contents:

id: The ID of the pico

eci: The main Wrangler ECI of the pico

name: The name of the pico

Example

myself_result = wrangler:myself()
/*
{
  "id": "cjhtji2op009hpkrq35bcpodh",
  "eci": "4bUS9W4HY5S1YfsAM9Ygw5",
  "name": "This Pico"
}
*/

name

Returns the name of the pico as recorded by Wrangler

Returns

A string containing the name of the pico

Example

name = wrangler:name()
/*
"wovyn_sensor"
*/

id

Returns the ID of the pico as recorded by Wrangler

Returns

A string containing the ID of the pico

Example

id = wrangler:id()
/*
"cjxeypfo900070jbzes8736w2"
*/

parent_eci

Returns a string containing an ECI to the parent of the pico. If no parent exists then it will return the empty string.

Returns

A string with the ECI of the parent pico. If no parent exists, then the string is the empty string.

Example

channel_to_parent = wrangler:parent_eci()
/*
"HdLRkvF2ADhMfERDScr4ng"
*/

randomPicoName

Returns a random English word that is unique among the children of the pico it is called on, if the pico has <= 200 children. Otherwise it will return a UUID.

Returns

A string that is a common English word

Example

random_name_result = wrangler:randomPicoName()
/*
"realize"
*/

getPicoMap

Returns the same data as wrangler:myself except it includes an ECI to the parent pico.

Returns

A map containing meta information about the pico, including its Wrangler ECI, its Wrangler name, the pico ID, and an ECI for the parent pico.

Example

thisPico = wrangler:getPicoMap()
/*
{
"name":"product",
"id":"cjxeypfo900070jbzes8736w2",
"parent_eci":"T2cuE5zaGrQzDS8NbDVs4y",
"eci":"Vn2TWkKeJYcj26gXSbiWr3"
}
*/

isMarkedForDeath

Returns true if this pico is in the process of being deleted. This function is used internally in Wrangler to lock tasks that cannot be interrupted by the pico being deleted, such as creating a new child pico. See Managing Pico Lifecycle for information on how to respond to notification of imminent pico deletion and allowing a ruleset to cleanup.

Returns

True if the pico is in the process of being deleted

False if the pico is not in the process of being deleted

Example

picoUnsafe = wrangler:isMarkedForDeath()
/*
true
*/

timeForCleanup

Returns the maximum amount of time given to a pico for its rulesets to cleanup before it is deleted. It is given in the format of the second parameter of the time:add() function.

Returns

A map containing the set time allowed for ruleset cleanup before a pico is deleted.

Example

timeToCleanup = wrangler:timeForCleanup()
/*
{ "minutes": 5 }
*/

getChild

Given the pico ID of a child of Wrangler return the associated child map. Fast as it is a map access.

Parameters

Parameter	Datatype	Description
id	String	Child pico ID to access.

Returns

Either

A child pico map for the relevant child of this pico.

NULL if the child does not exist

Example

childInfo = wrangler:getChild("cjxf0yqiz000o0jbz4kbrgczt")
/*
{
"parent_eci":"5ehT3zigTKhHuHL571dCF5",
"name":"refused",
"id":"cjxf0yqiz000o0jbz4kbrgczt",
"eci":"TR4zpDwpKtuYAbsmBG7Wd7"}
*/

childExists = wrangler:getChild("badID")
/*
null
*/

Received Events

create_child

wrangler:child_creation or wrangler:new_child_request

Creates a new child for this pico with optional arguments for the child's name, and rulesets to install on it upon creation. It is important to note any additional attributes passed to it will also be accessible to the newly created child and its rulesets as event attributes, as long as their keys do not conflict with the keys used for the internal event chain. See Managing Pico Lifecycle for a more in-depth explanation.

Attribute

Datatype

Description

name

String

The name for the new child pico. Will generate a random name if not provided.

rids

String Array

String

The RIDs of the rulesets to be installed on the new child pico. Each RID can be an entry in an array, or in a semicolon denoted list (e.g. "io.picolabs.ruleset_one;io.picolabs.ruleset_two").

Corresponding Raised Events:

Wrangler Full API#child_initialized

delete_child

wrangler:child_deletion or wrangler:delete_children

Deletes the direct child of this pico that has either the name or ID given as an event attribute. It will also delete that child's entire subtree of children. If both name and ID are given, they both will be evaluated. Deleting a child this way allows the child time for its rulesets to do any cleanup that they may have asked time for. It also cleans up parent-child channels, etc.

Attribute	Datatype	Description
name	String	The name of the children to be deleted.
id	String	The ID of the direct child to be deleted.
delete_all	Boolean	When true all children will attempt to be deleted.

Corresponding Raised Events:

Wrangler Full API#child_deleted

force_child_deletion

wrangler:force_child_deletion or wrangler:force_children_deletion

Through engine calls forcibly removes children picos without necessary direct interaction with the children and without any opportunity for cleanup. Allows for deletion of misbehaving picos, picos that do not comply with Wrangler's deletion process, and other such issues.

Attribute	Datatype	Description
name	String	The name of the children to be deleted.
id	String	The ID of the direct child to be deleted.
delete_all	Boolean	When true all children will attempt to be deleted.

Corresponding Raised Events:

Wrangler Full API#pico_forcibly_removed

child_sync

wrangler:child_sync

This event will both find children that Wrangler does not have recorded internally and delete children that Wrangler has recorded internally but do not exist anymore. Use this to detect any children added by rulesets other than Wrangler. Wrangler will ask the children first if they have Wrangler installed, if they do not then Wrangler will grab their admin channel through engine calls and add them to its children with a "rogue" attribute.

Corresponding Raised Events:

Raised Events

child_initialized

wrangler:child_initialized

This is sent from the child to the parent once the child is done initializing. You can react to new children being created using this event. This event also guarantees that any rulesets passed to the create_child event have been installed. Note that any attributes passed to the wrangler:child_creation will also be present.

Attributes

Attribute	Datatype	Description
parent_eci	String	The ECI that the child pico has to communicate with this pico (the parent).
name	String	The name of the new child pico
id	String	The pico ID of the new child pico
eci	String	An ECI for the parent to send events to the child pico. This is the same ECI in the map returned from the children() function.
rids	Array	This attribute reflects rulesets successfully installed by giving the RIDs to wrangler:child_creation. This will not reflect rulesets installed by giving rulesets to install by URL to wrangler:child_creation.
rids_to_install	String Array	Any RIDs that were requested to be installed upon initialization of the child. This includes RIDs given in the rids parameter of the create_child event. This may include RIDs that were not valid RIDs and were not able to be installed.

child_deleted

wrangler:child_deleted

This event is raised within the pico when a child of this pico has been deleted through use of wrangler:child_deletion.

Attributes

Attribute	Datatype	Description
name	String	The name of the pico that was just deleted
id	String	The pico ID of the child that was just deleted

child_creation_failure

wrangler:child_creation_failure

Raised when a pico is not able to be created. The most common cause of this is attempting to create a child pico with a duplicate name to another child pico.

Attributes

The same as the ones passed to wrangler:child_creation

pico_forcibly_removed

wrangler:pico_forcibly_removed

This event is raised within the pico when a child of this pico has been deleted through a force deletion using wrangler:force_child_deletion.

Attributes

Attribute	Datatype	Description
id	String	The pico ID of the child that was just deleted

ghost_children_added

wrangler:ghost_children_added

This event is raised as a result of a wrangler:child_sync event if any children that Wrangler did not have recorded are found. Their info is given in the attributes.

Attributes

Attribute	Datatype	Description
found_children	Map	A map of the children that have been found.

nonexistent_children_removed

wrangler:nonexistent_children_removed

This event is raised as a result of a wrangler:child_sync event if any children that Wrangler had recorded did not actually exist.

Attributes

Attribute	Datatype	Description
removed_children	Map	A map of the children that have been removed.