Data acquisition with PHP

Library

There is a convenient PHP library for interacting with Kotori over HTTP ready for download, see terkin-http.php. If you’re stuck with PHP4, see terkin-http.php4 for a version based on the PHP CURL binding and without namespaces.

Node API (highlevel)

Transmitting telemetry data using PHP is pretty easy, read on my dear:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
    // Put this file into the folder of your PHP program
    include("terkin-http.php");

    // Acquire HTTP API library
    use Terkin\TelemetryNode;

    // Create a "Node API" telemetry client object
    $telemetry = new TelemetryNode(
        "http://kotori.example.org/api",
        array(
            "realm"     => "mqttkit-1",
            "network"   => "testdrive",
            "gateway"   => "area-42",
            "node"      => "node-1",
        )
    );

    // Transmit data
    $data = array("temperature" => 42.84, "humidity" => 83);
    $telemetry->transmit($data);

Client API (lowlevel)

For transmitting telemetry data to an absolute uri, use the “Basic API” telemetry client object:

1
2
3
    // Create a "Basic API" telemetry client object
    use Terkin\TelemetryClient;
    $telemetry = new TelemetryClient("http://kotori.example.org/api/mqttkit-1/testdrive/area-42/node-1/data");

Demo

Command line

There is a command line program terkin-demo.php for demonstration purposes, it will send data to localhost:24642:

php -f clients/runtime/php/terkin-demo.php run demo
php -f clients/runtime/php/terkin-demo.php run sawtooth

Note

24642 is the default http port of Kotori. For making this work, Kotori should be configured similar to the canonical example configuration described in MQTTKit and Forwarding HTTP to MQTT.

The demo program in detail

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
<?php
// -*- coding: utf-8 -*-
/*
=====================================
Kotori telemetry demo program for PHP
=====================================

Documentation
-------------
https://getkotori.org/docs/handbook/acquisition/runtime/php.html#demo


Synopsis
--------
Run demonstration program from the command line::

    # Send fixed measurements "temperature" => 42.84, "humidity" => 83 for demonstration purposes
    php -f clients/runtime/php/terkin-demo.php run demo

    # Send a periodic, slowly oscillating sawtooth signal
    php -f clients/runtime/php/terkin-demo.php run sawtooth

*/

namespace DemoProgram {

    // Put this file into the folder of your PHP program
    include("terkin-http.php");

    // Acquire HTTP API library
    use Terkin\TelemetryNode;

    // When running from the command line, use some example programs
    // for submitting telemetry data for demonstration purposes.
    if (php_sapi_name() == "cli") {

        $telemetry = new TelemetryNode(
            "http://localhost:24642/api",
            array(
                "realm"     => "mqttkit-1",
                "network"   => "testdrive",
                "gateway"   => "area-42",
                "node"      => "node-1",
            )
        );

        if ($argc > 2) {
            $command = $argv[1];
            $subcommand = $argv[2];
        }

        if ($command == "run") {

            if ($subcommand == "demo") {
                // Emit single sample of a sawtooth signal
                $data = array("temperature" => 42.84, "humidity" => 83);
                var_dump($telemetry->transmit($data));

            } else if ($subcommand == "sawtooth") {
                date_default_timezone_set("Europe/Berlin");
                // Emit sample of a sawtooth signal each second, periodically
                while (true) {
                    $data = array("second" => intval(strftime("%S")));
                    var_dump($telemetry->transmit($data));
                    sleep(1);
                }
            }
        }

    }

}

?>

Todo

Todo

  • [o] After having export features, implement TelemetryClient->fetch(from, to) à la Grafana
  • [o] [docs] Reference from appropriate section in Hiveeyes system documentation
  • [o] [docs] Reference from handbook/kotori and setup/getting-started