darknetd: run darknet as a service, with a REST API

darknetd provides a service and API wrapper around the darknet command-line tool.

It allows you to efficiently run darknet YOLO image recognition on an "edge device", like Raspberry Pi or Jetson Nano, and access the results via a simple REST API.

Features

• Runs darknet as a service, avoiding startup time spent building the network and loading weights.
• Provides an API for viewing recent object detections, including access to raw source and prediction images.
• Works with external image capture tool (such as raspistill), allowing fine-tuning of camera settings.
• Archives recent darknet predictions.jpg images for review.
• Automatically deletes old images, ensuring your SD card/disk doesn't fill up.
• Exposes performance metrics in prometheus format.

Motivation

There are lots of great machine vision tools, but it's challenging to get them "into production" on remote edge devices. Performing the object detection on a commodity edge device offers many benefits:

• Images stay on the edge device (unless specifically requested), providing detection data without compromising privacy.
• Bandwidth usage is minimal for object detection API responses.
• The YOLOv3-tiny model can perform detection at about ~2 FPS on a Raspberry Pi and ~20 FPS on a Jetson Nano.
• Raspberry Pi4 Kit/Jetson Nano DevKit are $99 - 5MP camera module ~$20.

Quick start

1. Download and build darknet.
   • IMPORTANT: darknetd depends on a modified version of darknet! This small modification causes darknet to print bounding box information for detected objects.
   • We modified darknet-nnpack because it is optimized for the Raspberry Pi - you could easily apply this modification to the base darknet distribution instead.
   • darknetd assumes the darknet binary is at /usr/local/darknet/darknet.
   1. Install darknet per the README.
   2. Move the darknet directory to /usr/local/: mv darknet /usr/local/darknet
   3. Download the pre-trained YOLOv3-tiny weights: curl -o /usr/local/darknet/yolov3-tiny.weights https://pjreddie.com/media/files/yolov3-tiny.weights
   4. Confirm darknet is working from the command-line: cd /usr/local/darknet && ./darknet detect cfg/yolov3-tiny.cfg yolov3-tiny.weights data/dog.jpg
2. Setup the raspistill service - darknetd works hand-in-hand with this service.
   1. Get your camera working and verify you can capture images with raspistill: raspistill -o cam.jpg.
   2. Install the raspistill systemd file at /etc/systemd/system/raspistill.service.
   3. Review the raspistill.service file and customize camera/capture options as desired.
   4. Create the image archive directory: mkdir /tmp/cap
   5. Configure the raspistill service to start at boot: sudo systemctl enable raspistill
   6. Start the raspistill service: sudo systemctl start raspistill
   7. Verify images are being stored in /tmp/cap
3. Install darknetd:
   1. Download darknetd and install it at /usr/local/sbin/darknetd.
   2. Install the darknetd.service systemd file at /etc/systemd/system/darknetd.service.
   3. Configure darknetd to start at boot: sudo systemctl enable darknetd
   4. Start darknetd: sudo systemctl start darknetd

Usage

Darknetd has sensible defaults, and supports the following options - be sure to set them in your darknetd.service file.

Usage:
  darknetd [options]
  darknetd -h --help
  darknetd --version

Options:
  --capture-dir=<path>        Directory containing captured image - see raspiconfig.service [default: /tmp/]
  --capture-file=<file>       Filename of captured image - see raspiconfig.service [default: cap.jpg]
  --archive-dir=<path>        Directory containing image archive - see raspiconfig.service [default: /tmp/cap]
  --archive-files=<file>      Number of images to retain in archive [default: 240]
  --darknet-dir=<path>        Directory containing darknet installation [default: /usr/local/darknet]
  --darknet-data=<file>       Darknet data file, relative to darknet-dir [default: cfg/coco.data]
  --model-config=<file>       Darknet model config file, relative to darknet-dir [default: cfg/yolov3-tiny.cfg]
  --model-weights=<file>      Darknet model weights file, relative to darknet-dir [default: yolov3-tiny.weights]
  --detect-timeout=<secs>     Darknet detection timeout [default: 10]
  --detect-delay=<msec>       Darknet delay between detections in msec [default: 500]
  --listen-addr=<addr:port>   Darknet detection timeout [default: 0.0.0.0:8081]
  --version                   Show version
  -h, --help                  Show this screen

• To use a custom model: darknetd --darknet-data=cfg/YOUR.data --model-config=cfg/YOUR-MODEL.cfg --model-weights=YOUR-MODEL.weights
• Note that on a Pi4, setting --detect-delay below 200 msec can cause significant CPU load. The default of 500 is a reasonable balance of detection time and CPU usage.

API

WARNING: The API provides no authentication and is NOT intended to be exposed direclty to a public network!

• GET /objects - returns JSON list of most recent predictions
• GET /latest.jpg - returns latest source image
• GET /image/{imagename}.jpg - returns source or prediction image (get imagename from /objects output)
• GET /metrics - returns performance metrics in prometheus format
• GET /health - returns OK if healthy

Sample API request (note: returns up to 10 most recent detections):

$ curl -s localhost:8081/objects
[
  {
    "Image": "image208725.jpg",
    "PredImage": "predictions_image208725.jpg",
    "ImageTime": "2019-09-17T16:10:58.313756895-06:00",
    "PredTime": "2019-09-17T16:10:59.812694026-06:00",
    "TimeDetect": 0.767813,
    "TimeTotal": 0.893044895,
    "Objects": [
      {
        "Class": "person",
        "Prob": 85,
        "Left": 365,
        "Right": 445,
        "Top": 314,
        "Bot": 413
      }
    ]
  }
]
$ curl -s localhost:8081/image/image189401.jpg -o src_image.jpg
$ curl -s localhost:8081/image/predictions_image189401.jpg -o pred_image.jpg