Kapitel 4

Beacon Line RESTful API

Die Bline-Server RESTful API wird mit OpenAPI beschrieben (Version: 1.0.230924). Es bietet bei der Entwicklung und fortlaufenden Pflege eine Möglichkeit, über die API deren Implementation für Dokumentation und Tests in Einklang zu halten.

4.1.1 lines

Beacon Line Lines-Einstellungen.

4.1.2 line/{Name}

Key-Value Beispiele

4.2.1 anchors

Key-Value Beispiele

4.2.2 anchor/{AnchorID}

Key-Value Beispiele

4.2.3 anchor/{AnchorID}/broadcast?on={false/true}

Key-Value Beispiele

4.2.3 anchor/{AnchorID}/scan?on={false/true}

Key-Value Beispiele

4.2.4 anchor/{AnchorID}/connect/{MAC}

Key-Value Beispiele

4.2.5 anchor/{AnchorID}/disconnect/{MAC}

Key-Value Beispiele

4.2.6 anchor/{AnchorID}/handle/{MAC}/{Handle}

Die Struktur der Generic Attribute Profile (GATT) Tabelle eines BLE Peripheral Gerät herauszufinden (Discovery) ist ein energieintensiver Prozess...

4.3.1 nodes

Beacon Line Nodes Einstellungen.

4.3.2 node/{MAC}

Key-Value Beispiele

Unterabschnitte von Beacon Line RESTful API

4.1.1 lines

Beacon Line Lines Einstellungen.

key value
URL /{PREFIX}/lines
Method GET
Description Returns all Beacon Lines
Parameters N/A
Response JSON

Example:

#curl -X GET localhost:8080/bline/v1/lines
[
    {
        "anchors":1,
        "broadcast":false,
        "description":"",
        "enabled":true,
        "name":"line1",
        "scan":true,
        "url":"blgd-8c8e76011316:3001"
    },
    {
        "anchors":3,
        "broadcast":true,
        "description":"",
        "enabled":true,
        "name":"line2",
        "scan":true,
        "url":"blgd-8c8e76010477:3001"
    }
]

4.1.2 line/{Name}

key value
URL /{PREFIX}/line/{Name}
Method GET
Description Returns a Beacon Line by Name Parameters Name of Beacon Line [STRING]
Response JSON

Beispiel:

#curl -X GET localhost:8080/bline/v1/line/line1
{
    "anchors":1,
    "broadcast":false,
    "description":"",
    "enabled":true,
    "name":"line1",
    "scan":true,
    "url":"blgd-8c8e76011316:3001"
}
key value
URL /{PREFIX}/line/{Name}
Method PUT
Description Writes a Beacon Line by Name Parameters Name of Beacon Line [STRING]
Response JSON

Beispiel:

#curl -X PUT localhost:8080/bline/v1/line/line3
-H 'Content-Type: application/json'
-d '{"anchors":20,"broadcast":true,"description":"","enabled":true,"name":"line3","scan":true,"url":"blgd-8c8e7601441e:3001"}'
key value
URL /{PREFIX}/line/{Name}
Method DELETE
Description Deletes a Beacon Line by Name Parameters Name of Beacon Line [STRING]
Response JSON

Beispiel:

#curl -X DELETE localhost:8080/bline/v1/line/line3

4.2.1 anchors

key value
URL /{PREFIX}/anchors
Method GET
Description Returns all Anchors of a Beacon Line
Parameters N/A
Response JSON

Beispiel:

#curl -X GET localhost:8080/bline/v1/anchors
[
  {
    "Angle":0,
    "Description":"",
    "Fixed":false,
    "Location":"",
    "Url":"",
    "mac":"",
    "name":"line1-01"
  },
  {
    "Angle":0,
    "Description":"",
    "Fixed":false,
    "Location":"",
    "Url":"",
    "mac":"",
    "name":"line2-01"
  },
  {
    "Angle":0,
    "Description":"",
    "Fixed":false,
    "Location":"",
    "Url":"",
    "mac":"",
    "name":"line2-02"
  },
  {
    "Angle":0,
    "Description":"",
    "Fixed":false,
    "Location":"",
    "Url":"",
    "mac":"",
    "name":"line2-03"
  }
]

4.2.2 anchor/{AnchorID}

key value
URL /{PREFIX}/anchor/{AnchorID}
Method GET
Description Returns the full state of a specific Anchors
Parameters N/A
Response JSON

Beispiel:

#curl localhost:8080/bline/v1/anchor/line1-01
{
  "Angle":0,
  "Description":"",
  "Fixed":false,
  "Location":"",
  "Url":"",
  "mac":"",
  "name":"line1-01"
}

4.2.3 anchor/{AnchorID}/broadcast?on={false/true}

key value
URL /{PREFIX}/anchor/{AnchorID}/broadcast?on={false/true}
Method PUT
Description Switches the scan mode on or off
Parameters N/A
Response TEXT

Beispiel:

#curl -X PUT localhost:8080/bline/v1/anchor/line1-01/broadcast?on=true
Anchor: line1-01 broadcasting is active!

4.2.3 anchor/{AnchorID}/scan?on={false/true}

key value
URL /{PREFIX}/anchor/{AnchorID}/scan?on={false/true}
Method PUT
Description Switches the scan mode on or off
Parameters N/A
Response TEXT

Beispiel:

#curl -X PUT localhost:8080/bline/v1/anchor/line1-01/scan?on=false
Anchor: line1-01 scanning is stopped!

4.2.4 anchor/{AnchorID}/connect/{MAC}

Hinweis: Um eine Verbindung zu einem Peripheriegerät herzustellen, muss das Scannen des Ankers, der die Verbindung herstellen möchte, ausgeschaltet werden.

key value
URL /{PREFIX}/anchor/{AnchorID}/connect/{MAC}
Method PUT
Description Tries to connect the specified Anchor with the specified Node
Parameters N/A
Response TEXT

Beispiel:

#curl -X PUT localhost:8080/bline/v1/anchor/line1-01/connect/F6:49:C6:33:6D:B3
Anchor: line1-01 is connected to Node: F6:49:C6:33:6D:B3!

4.2.5 anchor/{AnchorID}/disconnect/{MAC}

key value
URL /{PREFIX}/anchor/{AnchorID}/disconnect/{MAC}
Method PUT
Description Disconnects the Amchor from the Node
Parameters N/A
Response TEXT

Example:

#curl -X PUT localhost:8080/bline/v1/anchor/line1-01/disconnect/F6:49:C6:33:6D:B3
Anchor: line1-01 is disconnected from Node: F6:49:C6:33:6D:B3!

4.2.6 anchor/{AnchorID}/handle/{MAC}/{Handle}

Handle:

Die Struktur der Generic Attribute Profile (GATT) Tabelle eines BLE Peripheral Gerät herauszufinden (Discovery) ist ein energieintensiver Prozess. Um es zu verhindern, verwenden wir die Handle Nummer auf der GATT-Tabelle. In dieser Methode kann der Beacon Line Anker (Central) die Characteristics Werte lesen und schreiben. Das bedeutet, dass zum Lesen oder Schreiben von einem bestimmten Characteristic die Handle Nummer für das Frontend Programm bekannt sein muss.

key value
URL /{PREFIX}/anchor/{AnchorID}/handle/{MAC}/{Handle}
Method GET
Description Reads a BLE handle of a Node over an Anchor
Parameters N/A
Response HEX

Beispiel:

#curl localhost:8080/bline/v1/anchor/line1-01/handle/F6:49:C6:33:6D:B3/13
00
key value
URL /{PREFIX}/anchor/{AnchorID}/handle/{MAC}/{Handle}
Method PUT
Description Writes a BLE handle of a Node over an Anchor
Parameters JSON
Response TEXT

Beispiel:

#curl -X PUT localhost:8080/bline/v1/anchor/line1-01/handle/F6:49:C6:33:6D:B3/13 -H 'Content-Type: application/json' -d '{"data":"0x01"}'
Anchor: line1-01 has written handle 13 on Node: F6:49:C6:33:6D:B3 with 01!

4.3.1 nodes

Beacon Line Nodes Einstellungen.

key value
URL /{PREFIX}/nodes
Method GET
Description Reads all BLE-Nodes
Parameters N/A
Response JSON

Beispiel:

#curl localhost:8080/bline/v1/nodes
[{
	"AnchorList": [{
		"AnchorID": "line1-01",
		"RSSI": -21,
		"Timestamp": 1695799643418
	}, {
		"AnchorID": "line1-01",
		"RSSI": -24,
		"Timestamp": 1695799644268
	}, {
		"AnchorID": "line1-01",
		"RSSI": -24,
		"Timestamp": 1695799644477
	}, {
		"AnchorID": "line1-01",
		"RSSI": -24,
		"Timestamp": 1695799644477
	}, {
		"AnchorID": "line1-01",
		"RSSI": -24,
		"Timestamp": 1695799645318
	}],
	"Connectable": true,
	"Data": "0201060dff7b0140000000b36d33c649f6",
	"LastAnchor": "line1-01",
	"LastTime": 1695799645318,
	"mac": "f6:49:c6:33:6d:b3",
	"name": ""
}]

4.3.2 node/{MAC}

key value
URL /{PREFIX}/node/{MAC}
Method GET
Description Reads all BLE-Nodes
Parameters MAC of Beacon, STRING
Response JSON

Beispiel:

#curl localhost:8080/bline/v1/node/F6:49:C6:33:6D:B3
{
	"AnchorList": [{
		"AnchorID": "line1-01",
		"RSSI": -47,
		"Timestamp": 1695801593893
	}, {
		"AnchorID": "line1-01",
		"RSSI": -44,
		"Timestamp": 1695801593518
	}, {
		"AnchorID": "line1-01",
		"RSSI": -41,
		"Timestamp": 1695801594169
	}, {
		"AnchorID": "line2-01",
		"RSSI": -20,
		"Timestamp": 1695801593518
	}, {
		"AnchorID": "line2-02",
		"RSSI": -47,
		"Timestamp": 1695801594328
	}],
	"Connectable": true,
	"Data": "0201060dff7b0140000000b36d33c649f6",
	"LastAnchor": "line1-01",
	"LastTime": 1695801594328,
	"mac": "f6:49:c6:33:6d:b3",
	"name": ""
}