-
Notifications
You must be signed in to change notification settings - Fork 99
Home
Horizon enables a "Programmable Edge" for Analytics and Cognitive Applications. See http://bluehorizon.network/ for more information. Anax is the core component of horizon, running on each system participating in horizon. This wiki page provides information about using specific aspects of anax.
Anax can run in 2 modes, or both at the same time, and there is an API for each:
Analytic/cognitive applications are sent to edge devices as a result of an agreement made between a data producer (normally an edge device) and a data consumer (normally an author of an analytic/cognitive application that is "served" by an agbot). Here is some information about the agreement process:
Horizon manages the lifecycle, connectivity, and resource caps of analytic/cognitive applications (workloads) it launches on edge devices. Some details:
- Horizon Managed Workload Detail
- Workload version rollback (documentation to be added)
The device id is the unique identifier of the edge device that is normally generated automatically by horizon (from, for example, the machine serial number). There are a few specific circumstances in which is it useful for the edge device owner to be able to override the generation of the device id:
- See How to Manually Change the Device ID (this information will move)
Ethereum is the default blockchain used by horizon to record agreements between producers (edge devices) and consumers (agreement bots/workload authors). By default a new set of ethereum credentials is automatically created for each edge device. But if currency will ultimately be exchanged for data produced (via horizon metering - see next section), it can be useful for a data producer to use the same ethereum credentials on all of the edge devices he/she owns. This can be accomplished by letting horizon create the ethereum credentials on your first edge device and then export/import them to all of your other edge devices:
- Export (capture) the ethereum credentials from your first edge device by downloading and running ethcap.sh:
cd /tmpCOMMON=/var/snap/bluehorizon/common /snap/bluehorizon/<revision>/scripts/anax/ethcap.sh
- The command above produces a file called
ethcreds.tar.gzthat contains the credentials. Copy this file to the/tmpdirectory of your other edge devices. - Import (restore) the ethereum credentials on your other devices by downloading and running ethrestore.sh before registering the device and services:
cd /tmpCOMMON=/var/snap/bluehorizon/common /snap/bluehorizon/<revision>/scripts/anax/ethrestore.sh ethcreds.tar.gz
- You can verify that the ethereum credentials are now the same by running the Horizon edge device API on all of your edge devices:
curl -sS http://localhost/status | jq .geth
Note* the above command shows the "eth_balance" as an empty array before the ethereum container (geth) is up and running (geth starts running after the device and service registration).
Metering records for agreements can be generated by horizon to record (ultimately on the blockchain) the amount/value of data a producer has given to a consumer. This can be used as the basis for value or currency exchange between the consumer and producer. The consumer should use the metering records in the blockchain and in its agbot to convert metering tokens into some value or currency that is transferred to the producer outside the Horizon platform. The steps required to read metering records from the blockchain and agbot APIs are documented in Reading Metering Records from the Blockchain. An overview of the steps to use metering records follows:
- Specify that metering records should be generated as part of an agreement, either in the edge device, the agbot policy file, or both. See Enabling Metering
- Ssh to your agbot and use the Agreement Bot API to find archived agreements that you want the metering records for.
- For example, to find the archived agreements for a particular device:
curl -sS http://localhost:8046/agreement | jq '.agreements.archived[] | select(.device_id =="<device-id>") | {device_id,policy_name,current_agreement_id,agreement_creation_time,terminated_description,metering_tokens} '
- For example, to find the archived agreements for a particular device:
- Follow the steps in Reading Metering Records to read the metering records from the blockchain, and convert those metering records to a specific value that can be transferred to the producer.
- Optionally delete agreements from the agbot that have been processed.
An agreement protocol is used by Horizon to define the mechanics of how an agreement is made and maintained within the Horizon platform. Horizon supports a choice of agreement protocols. The "Citizen Scientist" protocol is the default and it uses an ethereum blockchain to record agreements and metering. The "Basic" protocol is a simpler protocol that does not depend on a blockchain, but it shouldn't be used in an unknown/untrusted context. Both Devices and Agreement Bots can specify the use of a given agreement protocol.
In the policy file of an agreement bot, the agreement protocol choice is specified in the agreementProtocols section:
"agreementProtocols": [
{
"name": "Basic"
}
]
On a Device, each service can be registered with an agreement protocol by placing the chosen agreement protocol within the attributes list of the POST /service API:
"attributes": [
...
{
"id": "agreementprotocol",
"short_type": "agreementprotocol",
"label": "Agreement Protocol",
"publishable": true,
"mappings": {
"protocols": [
{"Basic":[]}
]
}
},
...
]
Agreements between producers and consumers using the Citizen Scientist protocol include the blockchain type and name. Producers and consumers can specify which blockchains they want to use. Producers indicate their choice(s) by configuring it through the Edge Device API on the agreementprotocol attribute (either a global attribute or an attribute specific to a service). Consumers indicate their choice(s) by specifying it in the agreementProtocols section of their policy file(s). Blockchain clients MUST be registered in the exchange by the same type and name referenced by the producer and consumer.
The producer and consumer choices MUST have a non-empty intersection for an agreement to be made. Intersection is done on blockchain type and name. If one party doesnt specify either, then it is assumed that the party doesnt care. When specifying blockchain type and name, it is important to know that the only blockchain type supported is "ethereum", and it is also the default. The default blockchain name is "bluehorizon". If both parties specify neither type nor name, " bluehorizon" will be chosen.