Kapitel 4

Beacon Line RESTful API

The Bline Server RESTful API is described using OpenAPI (version: 1.0.230924). It provides a way during development and ongoing maintenance to use the API to keep its implementation consistent for documentation and testing.

4.1.1 lines

Beacon Line Lines-settings.

4.1.2 line/{Name}

Key-Value Beispiele

4.2.1 anchors

Key-Value Beispiele

4.2.2 anchor/{AnchorID}

Key-Value Examples

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

Key-Value Examples

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

Key-Value Examples

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

Key-Value Examples

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

Key-Value Examples

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

Finding out the structure of the Generic Attribute Profile (GATT) table of a Bluetooth<sup>®</sup> Low Energy Peripheral device (discovery) is an energy-intensive process....

4.3.1 nodes

Beacon Line Nodes settings.

4.3.2 node/{MAC}

Key-Value Beispiele

Unterabschnitte von Beacon Line RESTful API

4.1.1 lines

Beacon Line Lines-settings.

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

Example:

#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

Example:

#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

Example:

#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

Example:

#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

Example:

#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

Example:

#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

Example:

#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}

Note: To connect to a peripheral device, scanning of the anchor that wants to connect must be turned off.

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

Example:

#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:

Finding out the structure of the Generic Attribute Profile (GATT) table of a Bluetooth® Low Energy Peripheral device (Discovery) is an energy intensive process. To avoid it, we use the handle number on the GATT table. In this method, the Beacon Line Anchor (Central) can read and write the Characteristics values. This means that to read or write from a specific characteristic, the handle number must be known to the frontend program.

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

Example:

#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 Bluetooth® Low Energy handle of a Node over an Anchor
Parameters JSON
Response TEXT

Example:

#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 settings.

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

Example:

#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 Bluetooth® Low Energy-Nodes
Parameters MAC of Beacon, STRING
Response JSON

Example:

#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": ""
}