MAXIBUS Universel - API Protocol (1.0.)

Download OpenAPI specification:Download

NT424 - V1.0 (08/2020)

Introduction

The MAXIBUS Universel Hub allows to centralize the alarm information of the SORHEA products. It consists in a motherboard managing 4 network bus, 8 alarm contacts. Additional alarm contacts are available with the 8-relay extension cards.

MAXIBUS Universel owns graphical interfaces but also exposes a HTTP API (Application Programming Interface). Your own applications can interact with MAXIBUS Universal data.

This HTTP API is based on the REST architecture style with representations in JSON format.

Audience

This documentation is intended for developers. They are expected to be familiar with REST constraints and JSON format.

Compatible versions

This document is compatible with Maxibus firmware version 3.4.3.

Documentation Content

This documentation shows principal requests to get alarms status in real time.

MAXIBUS Universel Alarms

On the Sorhea products, for each alarm trigger, alarms are locked for 4 seconds. After this laps of time, alarms will be reset.

MAXIBUS Universel HTTP API allows to get alarms functions of a network or a specific node.

Node definition

Nodes contains general information about a part of the Network. Depending on the configuration, a product may have severals nodes.

Nodes list functions of the product:

Kapiris :
- kapiris
Gfence :
- perimetre
- gestion
- zone
Solaris:
- solaris
- radio
- coordinateur
Maxiris:
- maxiris
Piramid:
- piramid
Coordinateur Connect:
- coordinateurConnect
- moduleConnect
- piramidConnect
- radioConnect
Connect
- connect
Apiris
- apiris zoning
- apiris no zoning

The content of nodes responses may be partially described because there are many parameters that are not always usefull.

Code Example

This is an example implemented in Python. It's a Login request followed by a getNetwork request. Get networks, Python example :

  # Get the Token
  url = 'http://' + IP_ADDRESS + '/api/' + 'login'
  data = '{"data": {"username" :"' + LOGIN + '", "password" : "' + PASSWORD + '"}}'
  response = requests.post(url, data=data).json()
  token = response['token']['token']

  # Get networks
  url ='http://' + IP_ADDRESS + '/api/' + 'networks' 
  response = requests.get(url, headers={'Authorization': 'Token ' + token})

Authentication

sorhea_auth

Token key to pass in Authorization Header. Add 'Token ' prefix before the apiKey.

Security scheme type:	API Key
Header parameter name:	Authorization

Login operation to get a valid Token

Request Body schema: application/json

username	string Username
password	string [ 1 .. 8 ] Password

Responses

200

Successful response

400

Bad request - Username/Pass missing

401

Unauthorized - Wrong Login/Pass

post /login

Maxibus server

/api/login

Request samples

Payload

application/json

Copy

Expand all Collapse all

{

"username": "string",
"password": "string"

}

Response samples

application/json

Copy

Expand all Collapse all

{

"login": false,
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
}

}

Network

Gets all `Network` (COM port) objects on Maxibus

Gets all Network (COM port) objects on Maxibus

Authorizations:

sorhea_auth

query Parameters

fields

required

Array of strings

Default: ["idNetwork,type,name,status,nbRadio,radios"]

List of object parameters Network.

Responses

200

Successful response

400

Bad Request : The URL is not as expected.

404

No content: no network found on Maxibus.

500

Internal server error.

get /networks

Maxibus server

/api/networks

Response samples

application/json

Copy

Expand all Collapse all

{

"login": "string",
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
},
"data":
{
- "networks":
  [
  - {
    "idNetwork": 1,
    "type": "maxiris",
    "name": "string",
    "status": "idle",
    "nbRadio": 0,
    "radios":
    [
    0
    ]
    }
  ]
}

}

Gets a specific `Network` from its network id.

Gets a specific Network from its network id.

Authorizations:

sorhea_auth

path Parameters

networkId

required

integer <uint8> [ 1 .. 4 ]

Id of the network

query Parameters

fields

required

Array of strings

Default: ["idNetwork,type,name,status,nbRadio,radios"]

List of objects parameters Network.

Responses

200

Successful response

400

Bad Request : The URL is not as expected or the network id is missing.

404

No content: no network found on Maxibus.

500

Internal server error.

get /networks/{networkId}

Maxibus server

/api/networks/{networkId}

Response samples

application/json

Copy

Expand all Collapse all

{

"login": "string",
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
},
"data":
{
- "network":
  {
  - "idNetwork": 1,
  - "type": "maxiris",
  - "name": "string",
  - "status": "idle",
  - "nbRadio": 0,
  - "radios":
    [
    0
    ]
  }
}

}

Nodes

Gets all `Node` objects on the selected network

Gets all Node objects on the selected network

Authorizations:

sorhea_auth

path Parameters

networkId

required

integer <uint8> [ 1 .. 4 ]

Id of the network

query Parameters

region	string World region. Needed only for solaris network. Value : ['europe', 'usa']. Should return null fields in Frequency if this field is empty
fields	Array of strings Default: ["all"] List of object parameters `Node`. 'type' field will be always given. i.e: fields=name,type
ignore	Array of strings Default: [] List of ignored fields. i.e : ignore=name,type,object.param

Responses

200

Successful response

400

Bad Request : The URL is not as expected.

404

No node found.

500

Internal server error.

get /networks/{networkId}/nodes

Maxibus server

/api/networks/{networkId}/nodes

Response samples

application/json

Copy

Expand all Collapse all

{

"login": "string",
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
},
"data":
{
- "nodes":
  [
  - {
    "idNetwork": 1,
    "idNode": 0,
    "type": "string",
    "enablePlanning": true
    }
  ]
}

}

Gets the selected `Node` on the selected network

Gets the selected Node on the selected network

Authorizations:

sorhea_auth

path Parameters

networkId required	integer <uint8> [ 1 .. 4 ] Id of the network
nodeId required	integer <uint8> [ 1 .. 256 ] Id of the node

query Parameters

fields	Array of strings Default: ["all"] List of object parameters `Node`. 'type' field will be always given. i.e: fields=name,type
ignore	Array of strings Default: [] List of ignored fields. i.e : ignore=name,type,object.param
region	string World region. Needed only for `Solaris` network (`Coordinateur`). Value : ['europe', 'usa']. Should return null fields in `NodeCoordinateurParamFrequency / NodeCoordinateurConnectParamFrequency` if this field is empty

Responses

200

Successful response

400

Bad request: the URL is not as expected.

404

No node found

500

Internal server error.

get /networks/{networkId}/nodes/{nodeId}

Maxibus server

/api/networks/{networkId}/nodes/{nodeId}

Response samples

application/json

Copy

Expand all Collapse all

{

"login": "string",
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
},
"data":
{
- "node":
  {
  - "idNetwork": 1,
  - "idNode": 0,
  - "type": "string",
  - "enablePlanning": true
  }
}

}

Alarms

Gets all the alarm objects on the selected network

Authorizations:

sorhea_auth

path Parameters

networkId

required

integer <uint8> [ 1 .. 4 ]

Network ID

Responses

200

Successful response

204

Wrong network id

404

Network not found

500

Internal server error.

get /networks/{networkId}/alarms

Maxibus server

/api/networks/{networkId}/alarms

Response samples

application/json

Copy

Expand all Collapse all

{

"login": "string",
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
},
"data":
[
- {
  - "alarms":
    {
    "alarmsList":
    [
    {
    "name": "DEFAULT_485",
    "state": "ACTIVE"
    },
    {
    "name": "DEFAULT_TECH",
    "state": "INACTIVE"
    }
    ],
    "idNetwork": 1,
    "idNode": 1,
    "nodeType": "perimetre"
    }
  },
- {
  - "alarms":
    {
    "alarmsList":
    [
    {
    "name": "DEFAULT_12V",
    "state": "ACTIVE"
    },
    {
    "name": "AUX1",
    "state": "ACTIVE"
    },
    {
    "name": "AP",
    "state": "ACTIVE"
    },
    {
    "name": "AUX2",
    "state": "ACTIVE"
    }
    ],
    "idNetwork": 1,
    "idNode": 2,
    "nodeType": "gestion"
    }
  },
- {
  - "alarms":
    {
    "alarmsList":
    [
    {
    "name": "DEFAULT_TECH",
    "state": "ACTIVE"
    },
    {
    "name": "INTRUSION",
    "state": "ACTIVE"
    }
    ],
    "idNetwork": 1,
    "idNode": 2,
    "nodeType": "zone",
    "triggeredSensor":
    {
    "Ampli": 107,
    "CDID": 2,
    "SensorID": 2,
    "UGAddr": 2
    }
    }
  }
]

}

Get all alarm objects on the selected node

Authorizations:

sorhea_auth

path Parameters

networkId required	integer <uint8> [ 1 .. 4 ] Network ID
nodeId required	integer <uint8> [ 1 .. 256 ] Id of the node

Responses

200

Successful response

400

Invalid Node Id

404

Network not found

500

Internal error system

get /networks/{networkId}/nodes/{nodeId}/alarms

Maxibus server

/api/networks/{networkId}/nodes/{nodeId}/alarms

Response samples

application/json

Copy

Expand all Collapse all

{

"login": "string",
"token":
{
- "user": "string",
- "token": "string",
- "expire": 0
},
"data":
{
- "alarms":
  {
  - "alarmsList":
    [
    {
    "name": "AP",
    "state": "INACTIVE"
    },
    {
    "name": "AUX",
    "state": "ACTIVE"
    },
    {
    "name": "ANTI_MASK",
    "state": "INACTIVE"
    },
    {
    "name": "INTRUSION",
    "state": "ACTIVE"
    }
    ],
  - "idNetwork": 1,
  - "idNode": 1,
  - "nodeType": "kapiris"
  }
}

}