Phi: a real-time programming language for connected devices

Assetwolf supports Phi, a simple language for running calculations and small programs in real-time.

Why do I need Phi?

When assets send data to an Assetwolf IoT portal, Assetwolf can process that data through its rules engine. Those rules can be really simple—such as "raise an alert if sensor reading exceeds [threshold]"—or by using a simple form of program code, they can be far more sophisticated.

For example, you may want to:

• compare a latest value with others in that device's row of data
• compare the value with data from other devices nearby
• compare the value with previous data from that device
• perform scientific calculations on any of the above data (such as sine, cosine, mean, standard deviation, etc.)
• perform simple program logic (such as for loops, and if...else logic).

The Phi programming language allows those things to be done.

How do I get see the Phi interface?

You can see the Phi programming interface when editing a Schemas in an Assetwolf portal.

The Schemas page specifies:

• meta data fields (i.e. static data fields)
• for an Asset definition, incoming data fields; or for a Data Pool definition, source data fields
• the calculated data fields
• how the calculations are performed (this where Phi comes in).

If you have an Assetwolf portal, simply go to Setup->Schemas, pick a schema and edit it, and you will see where Phi calculations can be entered.

What does Phi code look like?

Phi code is a language with C-style syntax. Variables can be defined like this:

a = 1
b = 'List of Important Bird Areas in Michigan'

In Phi, semi-colons are not needed and each statement is on one line of code. Statements can't span multiple lines, however you can use semi-colons to put multiple statements on the same line:

greetingOfChoice = 'hello'; recipient = 'world'

String concatenation is done using the ~ operator:

message = greetingOfChoice ~ ' ' ~ recipient

...or the paste() function (which automatically adds a space):

message = paste(greetingOfChoice, recipient)

You can use single or multi-line comments, e.g.:

#Single line comment (using a hash-sign)
//Single line comment (using two forward-slashes)
/*
	Multi-line comment
*/

You can use standard mathematical operations, e.g.:

a = 1 + 2
print(a)	#3

a += 1
print(a)	#4

a++
print(a)	#5

a = 2 * 3
print(a)	#6

a = 8 - 1
print(a)	#7

a = 2 ^ 3
print(a)	#8

a = 21 % 12
print(a)	#9

While writing Phi code, you can use the print() function to check the contents of variables. (This only has an effect while testing; the data-processor ignores this function.)

if statements work like this:

shaken = true; stirred = false; speed = 12

if (shaken and not stirred) {
	beverage = 'cocktail'

} else if (speed == 88) {
	beverage = 'cola'

} else {
	beverage = 'tea'
}

You can also use &&, || and ! instead of and, or, and not, e.g.:

if (shaken && !stirred) {

for loops have three different forms:

#Fixed range
for (i in 1:10) {
	print(i)
}

#Looping through an array
numbers = [2, 3, 5, 7]
for (p in numbers) {
	print(p)
}

#Looping through an object
colors = {red: 0xff0000, green: 0x00ff00, blue: 0x0000ff}
for (color, code in colors) {
	print(color, code)
}

You can use continue and break in loops, e.g.:

primes = []
for (i in 1..100) {
	if (i < 2) {
		isPrime = false
	
	} else if (i == 2) {
		isPrime = true
		
	} else {
		isPrime = true
		stop = i - 1
		
		for (j in 2..stop) {
			if (i % j == 0) {
				isPrime = false
				break
			}
		}
	}
	
	if (!isPrime) {
		continue
	}
	primes[] = i
}

There is only one line of code in an if or a for, you can commit the { and }, though this makes the code less readable:

n = -3
if (n < 0)
	n = abs(n)

Finally, you can use the return() function to return a value. If you omit the return() function, then the value of the last line of your code will be used instead.

How does Phi code refer to IoT data?

There are four sources of IoT data:

• meta data (about an asset, or a schema itself)
• incoming data from "this asset" (for asset schemas only)
• data from assets underneath the current data pool in the hierarchy (for data pool schemas only)
• previous data that occurred for "this asset" or "this data pool" at some time in the past.

Here are the variables in more detail.

Phi variables in more detail

Here are all available variables.

For assets only

The thisRow object will contain the row from the database that's currently being processed by the data-processor.

* The "value" array is the simple way to get to the latest value of a field, and does not discern between known and assumed values. (Remember that Assetwolf supports rows of data coming from assets in which fields may be missing. When the asset sends data but a field on its schema is missing, the last-known value is inserted into the database, with a flag to say it was "assumed".)

Examples

#If you just want the most recent value for the light level, and don't care if it was assumed
lightLevel = thisRow.value.lightlevel

#If you want more details about when the value for the light level was received
if (thisRow.actual.lightlevel is not null) {
	lightLevel = thisRow.actual.lightlevel
	lightLevelTS = thisRow.timestamp
	lightLevelWasAssumed = false
} else {
	lightLevel = thisRow.lastKnown.lightlevel
	lightLevelTS = thisRow.lastKnownAt.lightlevel
	lightLevelWasAssumed = false
}

For data pools only

Data pools are "big picture" views of data, and can display data that has been processed and aggregated for multiple assets, or for multiple data pools. Data pools are in a hierarchy. For example, a Location can have a data pool gathering data from Areas, or within it an Area can have a data pool gathering data from individual Assets.

The data processor processes each data pool when all of its "source" data pools have presented data, or one of its source data pools has presented data more than once. (You can think of them as "child", or "subordinate" data pools.) The source refers either to data coming from an assets under the current data pool, or from the assets in the data pool.

When this occurs, the data processor runs, and a program may contain the following variables.

Examples

#Get the highest/lowest/average/total values
maxLightLevel = max(source.values.lightlevel)
minLightLevel = min(source.values.lightlevel)
totalLightLevel = sum(source.values.lightlevel)
averageLightLevel = mean(source.values.lightlevel)

//N.b. the sources are arrays of data, so you can loop through them
maxLightLevel = 0
minLightLevel = Infinity
totalLightLevel = 0
for (lightLevel in source.values.lightlevel) {
	if (maxLightLevel < lightLevel) {
		maxLightLevel = lightLevel
	}
	if (minLightLevel > lightLevel) {
		minLightLevel = lightLevel
	}
	totalLightLevel += lightLevel
}
averageLightLevel = totalLightLevel / count(source.values.lightlevel)

For both assets and data pools

Both asset and data pool schemas have the following variables.

Examples

activationsThisTime = thisRow.value.activations - prevRow.value.activations
activationsPerSecond = activationsThisTime * 1000 / (thisRow.timestamp - prevRow.timestamp)

Functions

There are several functions available that refer to data nodes in any hierarchy of data pools and assets:

Examples

activationsThisWeek = thisRow.value.activations - getHistoricValue('activations', '1 week ago')
setValue('activations_this_week', activationsSinceLastWeek)

Advanced usage

Phi is based on a subset of the Twig language.

Any basic expression, filter or operator from Twig will also work in Phi, for example:

n = -12
print(n|abs)		#12

print(1 is odd)		#true
print(1 is even)	#false

colour = 'Red'
t = "my car is #{colour}"

print(t)			#"my car is Red"
print(t|lower)		#"my car is red"
print(t|upper)		#"MY CAR IS RED"
print(t|capitalize)	#"My car is red"
print(t|title)		#"My Car Is Red"

r = t|replace({car: 'van'})
print(r)			#"my van is Red"

x = 1; y = 2
t = "#{x} plus #{y} is #{x + y}"
print(t)					#"1 plus 2 is 3"

n = 1.234e7
print(n|number_format)		#"12,340,000"


numbers = [4, 5, 6]
print(numbers|join(','))	#"4,5,6"

fruit = "apple,banana,cherry"
print(fruit|split(','))		#["apple", "banana", "cherry"]

t = '  Hello world '
print(t starts with 'H')	#false
print(t ends with 'd')		#false
t = t|trim
print(t) #"Hello world"
print(t starts with 'H')	#true
print(t ends with 'd')		#true

print(t matches '/hello/')	#0
print(t matches '/Hello/')	#1
print(t matches '/hello/i')	#1
print('Hello' in t)			#true
print('Hi' in t)			#false

Note that Twig's environment functions such as constant(), include(), parent() and source() do not work in Phi.