eladbar/ip2mqtt

By eladbar

•Updated over 5 years ago

Image Processing to MQTT

Image

3.6K

Overview Tags

eladbar/ip2mqtt repository overview

⁠IP2MQTT

⁠Description

Image processing to MQTT message docker based solution, Provides an integration between image processors (DeepStack or MachineBox) using an image data source (Local file, Snapshot of camera, BlueIris, etc...) to publish the result via MQTT message.

Service contain web API layer to manage data sources, face's definition and manage processed images.

In most of the processing engines, the processing result will include the image name with confidence level, To allow multiple trained images for a specific person, when training a face through the IP2MQTT it will ask for name, Later in the MQTT message of processing, the name will return and will allow to invoke automation on the person level and not the image level.

⁠How to

⁠Requirements

DeepStack or MachineBox configure
Data sources link
Docker environment

⁠Installation

⁠Manual

docker run -p 10080:10080 \
     -v /etc/localtime:/etc/localtime:ro \
     -v /etc/timezone:/etc/timezone:ro \
     -v {pwd}/appsettings.json:/app/appsettings.json \
     -v {pwd}/Configuration.json:/app/Configuration.json \
     -v {pwd}/log4net.config:/app/log4net.config \
     -v {pwd}/data/:/app/Data/ \
     -e UseAPIKey=false \
     -e APIKey=None \
     -e ProcessingEngineHost=URL \
     -e ProcessingEnginePort=Port \
     -e ProcessingEngineAPIKey=Key \
     -e ProcessingEngineIsSSL=false \
     -e ProcessingEngineTimeout=60 \
	 -e ProcessingEngineParallelProcessing=false \
     -e ProcessingEngine=DeepStack \
     -e MQTTBrokerHost=MQTTBroker \
     -e MQTTBrokerPort=MQTTPort \
     -e MQTTBrokerUsername=Username \
     -e MQTTBrokerPassword=Password \
     -e MQTTBrokerTopicPrefix=IP2MQTT --name ip2mqtt eladbar/ip2mqtt:latest

⁠Docker compose

version: '2'
services:       
  ip2mqtt:
    image: "eladbar/ip2mqtt:latest"
    container_name: "ip2mqtt"
    hostname: ip2mqtt
    environment:
      - UseAPIKey=false
      - APIKey=None
      - ProcessingEngineHost=URL
      - ProcessingEnginePort=Port
      - ProcessingEngineAPIKey=Key
      - ProcessingEngineIsSSL=false
      - ProcessingEngineTimeout=60
	  - ProcessingEngineParallelProcessing=false
      - ProcessingEngine=DeepStack
      - MQTTBrokerHost=MQTTBroker
      - MQTTBrokerPort=MQTTPort
      - MQTTBrokerUsername=Username
      - MQTTBrokerPassword=Password
      - MQTTBrokerTopicPrefix=IP2MQTT
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
      - {pwd}/appsettings.json:/app/appsettings.json
      - {pwd}/Configuration.json:/app/Configuration.json
      - {pwd}/data/:/app/Data/
    ports:
      - "10080:10080"

⁠Environment Variables

Variables	Type	Required	Default	Description
UseAPIKey	boolean	yes	false	IP2MQTT API security layer, in case set to `true`, any request to the API, will return HTTP Status Code 403 if provided APIKey is wrong or not provided, use `true` when API exposed to the world
APIKey	string	no	-	IP2MQTT API security layer, completes the `UseAPIKey` functionality
ProcessingEngine	string	yes	DeepStack	Available options are DeepStack or MachineBox, defines which engine to activate
ProcessingEngineHost	string	yes	-	Hostname of the chosen procssing engine, accepts CSV format of multiple engine's URLs (on the same port)
ProcessingEnginePort	integer	yes	80	Port of the processing engine
ProcessingEngineAPIKey	string	no	-	Can be used for DeepStack only, API key for security in case set in DeepStack docker
ProcessingEngineIsSSL	boolean	yes	false	Processing engine's URL is HTTPS or HTTP
ProcessingEngineTimeout	integer	yes	10	Period of time in second to declare timeout in case response from processing engine didn't come back
MQTTBrokerHost	string	yes	-	Hostname or IP of the MQTT Broker
MQTTBrokerPort	integer	yes	-	Port of the MQTT Broker
MQTTBrokerUsername	string	no	-	Username of the MQTT Broker
MQTTBrokerPassword	string	no	-	Password IP of the MQTT Broker
MQTTBrokerTopicPrefix	string	yes	IP2MQTT	Hostname or IP of the MQTT Broker

⁠Setup

to start using the service, please follow the API documentation to set faces and data sources

⁠General API security notes

When calling the API if using UseAPIKey and APIKey, requests should include:

GET - in the query string, additional parameter APIKey with the key set in the docker installation
POST - in the body, additional parameter APIKey with the key set in the docker installation

⁠API

⁠GET /api/Camera

Returnes list of camera / image sources defined

⁠Response HTTP Status codes

Status	Description
200	Configuration reterived correctly

⁠Response

[
  {
    "name": "string",
    "url": "string",
    "username": "string",
    "password": "string",
    "timeout": 0
  }
]

Variables	Type	Description
Name	string	Name of the image source
Url	string	URL to the image
Username	string	Username of the camera data source
Password	string	Password of the camera data source
Timeout	int	Default timeout to cancel processing, in case image didn't return in that time frame

⁠POST /api/Camera

Add or update camera / image source

⁠Request

{
  "name": "string",
  "url": "string",
  "username": "string",
  "password": "string",
  "timeout": 0
}

Variables	Type	Description
Name	string	Name of the image source
Url	string	URL to the image
Username	string	Username of the camera data source
Password	string	Password of the camera data source
Timeout	int	Default timeout to cancel processing, in case image didn't return in that time frame

⁠Response HTTP Status codes

Status	Description
200	Updated
201	Added
304	Configuration was not changed

⁠DELETE /api/Camera

Delete a specific camera / image source

⁠Request

Variables	Type	Description
Name	string	Name of the image source

⁠Response HTTP Status codes

Status	Description
200	Deleted
404	Configuration was not changed

⁠GET /api/Face

Returnes list of faces defined

⁠Response HTTP Status codes

Status	Description
200	Configuration reterived correctly

⁠Response

[
  {
    "name": "string",
    "images": [
      "string"
    ]
  }
]

Variables	Type	Description
Name	string	Name of the person
Images	string's array	Images trained for that person

⁠POST /api/Face

Train person's face

⁠Request

{
  "personName": "string",
  "imageName": "string",
  "imageUrl": "string"
}

Variables	Type	Description
Person name	string	Name of the person
Image name	string	Name of the image to be sent to the processing engine
Image URL	string	URL of the image to train

⁠Response HTTP Status codes

Status	Description
200	Trained
304	No need to train, person and image already trained
400	Failed validation

⁠POST /api/Face/Test

Test trained person's face

⁠Request

{
  "imageUrl": "string"
}

Variables	Type	Description
Image URL	string	URL of the image to test

⁠Response

{
  "isSuccessful": true,
  "faces": [
    {
      "userId": "string",
      "status": 0,
      "confidence": 0,
      "imageId": "string"
    }
  ],
  "started": "2020-05-16T06:19:10.230Z",
  "completed": "2020-05-16T06:19:10.230Z"
}

Variables	Type	Description
isSuccessful	boolean	Image processed correctly
faces	face's array	Array of faces
started	date & time	Date started processing
completed	date & time	Date completed processing

Face object

Variables	Type	Description
userId	boolean	Name of the person
status	integer	Processing status (0=NotFound,1=Unidentified, 2=Unregistered, 3=Identified, 4=Failed)
confidence	decimal	value between 0 t0 1 represents the confidence level (e.g. 0.9=90%)
imageId	string	Name of the image

⁠Response HTTP Status codes

Status	Description
200	Processed
400	Failed validation

⁠DELETE /api/Face

Delete a specific trained image for a person, in case the image is the only one for that personm person will be deleted as well

⁠Request

Variables	Type	Description
Person name	string	Name of the person
Image name	string	Name of the image related to that person

⁠Response HTTP Status codes

Status	Description
200	Deleted
304	Not modifed
400	Person doesn't contain the image name

⁠GET /api/Image

Returnes an image related to past process based on token available in the corresponding MQTT message sent

⁠Request

Variables	Type	Description
Token	string	string represents an image from an MQTT message sent by IP2MQTT

⁠Response HTTP Status codes

Status	Description
200	Image available
404	Image is not available

⁠GET /api/Image/Metadata

Returnes an JSON as sent in MQTT message related to past process based on token available

⁠Response HTTP Status codes

Status	Description
200	Metadata available
404	Metadata is not available

⁠Response

See below MQTT Message format description

⁠DELETE /api/Image

Delete a specific image from cache based on token

⁠Request

Variables	Type	Description
Token	string	string represents an image from an MQTT message sent by IP2MQTT

⁠Response HTTP Status codes

Status	Description
200	Deleted
404	Not deleted

⁠Process

⁠Internal flow and outcome

Scheduler invokes every 1 second per camera Process image
Scheduler invokes every 30 seconds

⁠MQTT Messages

⁠Process message (IP2MQTT/Process)

MQTT Message format

{
  "faces": [
    {
      "userId": "string",
      "status": 0,
      "confidence": 0,
      "imageId": "string"
    }
  ],
  "camera": "string",
  "token": "string",
  "downloadStarted": "2020-05-16T07:56:57.679Z",
  "downloadCompleted": "2020-05-16T07:56:57.679Z",
  "processStarted": "2020-05-16T07:56:57.679Z",
  "processCompleted": "2020-05-16T07:56:57.679Z",
  "time": "2020-05-16T07:56:57.679Z",
  "status": true
}

Variables	Type	Description
Faces	face's array	Array of faces
Camera	string	Name of camera / image source
Token	string	Represents the id to reterive the image from cache
Download started	date & time	Represents when download image began
Download completed	date & time	Represents when download image completed
Process started	date & time	Represents when process image against the procssing engine began
Process completed	date & time	Represents when process image against the procssing engine completed
Time	date & time	Represents when message sent to the MQTT broker
Status	boolean	Faces identified?

Face object

Variables	Type	Description
userId	boolean	Name of the person
status	integer	Processing status (0=NotFound,1=Unidentified, 2=Unregistered, 3=Identified, 4=Failed)
confidence	decimal	value between 0 t0 1 represents the confidence level (e.g. 0.9=90%)
imageId	string	Name of the image

⁠Sattus and Statistics (IP2MQTT/Status)

{
  "Status": "Started",
  "LastUpdate": "2020-05-16T10:58:58.0972614+03:00",
  "ImageProcessed": 1,
  "ImageDownloaded": 1,
  "CameraList": [ "Camera1", "Camera2" ]
}

Variables	Type	Description
Status	string	Available status - NotStarted, Starting, Started, NoImageProcessor, Stopping, Stopped
Last update	date & time	Time stamp of last processing
Image processed	integer	Number of images processed since startup
Image download	integer	Number of images downloaded since startup
Camera list	string's array	Names of available camera or image sources

⁠NodeRED Flow

https://github.com/elad-bar/IP2MQTT/blob/master/IP2MQTT-NodeRED.PNG⁠

Tag summary

Recent tags

Content type

Image

Digest

Size

90.3 MB

Last updated

over 5 years ago

docker pull eladbar/ip2mqtt