diff --git a/docs/unix_service.md b/docs/unix_service.md new file mode 100644 index 0000000..514cdd2 --- /dev/null +++ b/docs/unix_service.md @@ -0,0 +1,102 @@ +# Creating a Service for Neolink + +This will guide you through creating a service for neolink that +can be used on linux machines such as ubuntu and debian +buster/stetch or any other os that uses systemd. + +The general steps are: + +1. Create an unprivileged user to run neolink +2. Setting up neolink somewhere the unprivileged user can run it +3. Creating the service file + +## Creating the unprivileged user + +For this I will use the username neolinker. Any unused name would be fine. + +``` +sudo adduser --system --no-create-home --shell /bin/false neolinker +``` + +Depending on your flavour of linux `adduser` may have also created +a group of the same name. If it did not, you can create a group with: + +``` +sudo addgroup --system neolinker +``` + +## Setting up neolink + +For this we will put neolink in `/usr/local/bin` and the config in `/usr/local/etc` but any directory readable by the `neolinker` user would be fine. + +We will also secure the config file so that only neolinker (and root) can read it. We want to do this because it contains passwords. + +``` +sudo cp neolink /usr/local/bin/neolink +sudo cp my_config.toml /usr/local/etc/neolink_config.toml +sudo chmod 755 /usr/local/bin/neolink +sudo chown neolinker:neolinker /usr/local/etc/neolink_config.toml +sudo chmod 600 /usr/local/etc/neolink_config.toml +``` + +## Creating the service + +We will create a systemd service. This service will need to point to our files for using neolink and also instruct it to start with our unprivileged user. + +Create a file here `/etc/systemd/system/neolink.service` with the following contents: + +``` +[Install] +WantedBy=multi-user.target + +[Unit] +Description=Neolink service + +[Service] +Type=simple +ExecStart=/usr/local/bin/neolink --config /usr/local/etc/neolink_config.toml +Restart=on-failure +User=neolinker +Group=neolinker + +``` + +And that's it + +## Controlling the Service + +You can now control the service with the usual commands + +To start it use: + +``` +systemctl start neolink +``` + +To stop it use: + +``` +systemctl stop neolink +``` + +To check it's running use: + +``` + +systemctl status neolink + +``` + +To make it run at startup from now on: + +``` + +systemctl enable neolink + +``` + +You can check it's log file with + +``` +journalctl -xeu neolink +``` diff --git a/docs/unix_setup.md b/docs/unix_setup.md new file mode 100644 index 0000000..2daf311 --- /dev/null +++ b/docs/unix_setup.md @@ -0,0 +1,291 @@ +# Setting up Neolink on Linux + +This will go through the first steps of adding neolink onto a +linux based computer. + +There are many flavours of linux so the name of some packages +may not exactly match. You are expected to be able to find the +correct names yourselves. + +1. Install dependancies + +2. Download neolink + +3. Setup the config + +4. Run neolink + +## Installing the Dependencies + +The dependencies for neolink include: + +- Gstreamer RTSP server + +- Gstreamer good plugin set + +- Gstreamer bad plugin set + +- glib 2.0 + +Glib2.0 is usually already installed on most modern unix flavours. +But the others will likely need to be installed via your package +manager. + +Here are some examples for command packages that work on some distros + +- ubuntu, buster, stretch + + ```bash + sudo apt install \ + libgstrtspserver-1.0-0 \ + libgstreamer1.0-0 \ + libgstreamer-plugins-bad1.0-0 \ + libgstreamer-plugins-good1.0-0 \ + gstreamer1.0-plugins-good \ + gstreamer1.0-plugins-bad + ``` + +- arch, manjaro + + ```bash + sudo pacman -S \ + gstreamer \ + gst-plugins-bad \ + gst-plugins-good \ + + # You will need this from AUR, and therefore need to install + # yay first (see below if you haven't done this yet) + sudo yay -S \ + gst-rtsp-server + ``` + + If your on archlinux or manjaro and you need to install yay do this: + + ```bash + git clone https://aur.archlinux.org/yay.git + cd yay + makepkg -si + ``` + +## Downloading neolink + +You now need to get a copy of neolink. You can get that from this +github [under the CI assets](https://github.com/thirtythreeforty/neolink/actions?query=branch%3Amaster+workflow%3ACI). + +Currently only amd64 is officially released, but armv7 will soon +be available too. + +If you are installing on a raspberry pi, you will need to compile +from source until the official armv7 builds are available. + +You will get a zip file called `release-ubuntu-18.04.zip`, unzip it with + +```bash +unzip "release-ubuntu-18.04.zip" +``` + +This will extract two files called `neolink` and `neolink.d`. These are +the binaries we will be using. + +## Setting up the Configuration File + +Neolink uses a toml file for configuration. A sample toml can be found in the +source code called `sample_config.toml`. + +You can download it with + +```bash +curl -LJO 'https://github.com/thirtythreeforty/neolink/raw/master/sample_config.toml' +``` + +Open up the file in your favourite text editor. + +For the most basic setup you need to change only the parts in `[[ cameras ]]`. +Neolink can connect to any number of supported reolink cameras at once. Each +camera requires its own `[[ cameras ]]` block. Here is the example one: + +```toml +[[cameras]] +name = "driveway" +username = "admin" +password = "12345678" +address = "192.168.1.187:9000" +``` + +Set the `name` to any value you want, this will be the name of the rtsp stream. +In this tutorial I will assume you leave as "driveway". + +The username and password are the ones that are used to connect to the camera +and are the same ones used in the official reolink app. + +The address is the ip address of the camera. You should set and use a fixed ip +for your camera. There are many ways to get a fixed ip address for your camera +including changing the settings in the reolink app. +Or my personal favourite assigning I fixed DHCP address from your router. How +to do either of these things is beyond the scope of this tutorial. + +- Note for E1 and Lumos + + If your camera is an `E1` or a `Lumos` you will need to add the `format` line + to your `[[ cameras ]]` block like this: + + ```toml + [[cameras]] + name = "driveway" + username = "admin" + password = "12345678" + address = "192.168.1.187:9000" + format = "h264" + ``` + + This will tell neolink that this camera uses the H264 format for its video. + Future version of neolink will auto detect this. + +Set up as many `[[ cameras ]]` as you want and save the file as `my_config.toml` + +## Running Neolink + +We are now ready to run neolink. Open up and terminal and navigate the the +folder where you `neolink` and `my_config.toml` are. + +Run neolink with: + +``` +./neolink --config my_config.toml +``` + +You should see a message such as: + +``` +[DATE TIME INFO neolink] Neolink 0.3.0 (unknown commit) release +[DATE TIME INFO neolink] camera: Connecting to camera at xxx.xxx.xxx.xxx:9000 +[DATE TIME INFO neolink] camera: Connecting to camera at xxx.xxx.xxx.xxx:9000 +[DATE TIME INFO neolink] camera: Connected to camera, starting video stream mainStream +[DATE TIME INFO neolink] camera: Connected to camera, starting video stream subStream +``` + +Neolink should now be running :) + + +## Testing with ffprobe + +To test neolink we will use `ffprobe`. + +If you do not have `ffmpeg` installed yet do it now through your package +manager: + +```bash +sudo apt intall ffmpeg +``` + +You must leave neolink running at the same time you run ffprobe. Neolink is a +translator and it cannot translate reolink -> rtsp if you close it. The easiest +way to do this is to open two terminals. One with neolink running and the other +we will use for running ffprobe. + +In a neo terminal run: + + +```bash +ffprobe rtsp://127.0.0.1:8554/driveway +``` + +Where you replace `driveway` with the name of your camera. + +A successful run should report something like this at the end: + +``` +Input #0, rtsp, from 'rtsp://127.0.0.1:8554/driveway': + Metadata: + title : Session streamed with GStreamer + comment : rtsp-server + Duration: N/A, start: 0.114267, bitrate: N/A + Stream #0:0: Video: h264 (High), yuv420p(progressive), 2304x1296, 90k tbr, 90k tbn, 180k tbc +``` + +You should also test the lower resolution subStream: + +```bash +ffprobe rtsp://127.0.0.1:8554/driveway/subStream +``` + +If the mainStream fails but the subStream succeeds you may need to add +`format = "h264"` to your `[[ cameras ]]` section of your config. + +## Common Errors + +- Missing dependancies + + If you get a message such as: + + ``` + libgstrtspserver-1.0.so.0: cannot open shared object file: No such file or directory + ``` + + You have not installed all of the dependencies repeat the `Installing the Dependencies` + section of this guide. + +- Not turned on + + If when using ffprobe to test you get: + + ``` + Connection to tcp://xxx.xxx.xxx.xxx:8554?timeout=0 failed: Connection refused + rtsp://xxx.xxx.xxx.xxx:8554/driveway: Connection refused ``` + ``` + + You have probably closed neolink. You should leave it running in an open + terminal window whenever you want to use it. If you want to run it in the + background, consider following the unix_service guide in the `docs/` folder + of the source code. + +- More advanced debugging required + + For other errors you will need to enable more debugging messages before + running neolink for better diagnoses. To do this stop neolink and restart it + with this command. + + ```bash + GST_DEBUG=3 ./neolink --config my_config.toml + ``` + + This will print out a lot more information to the terminal. Try to connect + to it with ffprobe and read the error messages it generates. + + - Advanced debugging: Missing plugins + + If while running advanced debugging you get the message: + + ``` + GST_ELEMENT_FACTORY gstelementfactory.c:456:gst_element_factory_make: no such element factory "h265parse"! + ``` + + This means that you are missing the gstreamer plugins. You must have both + the good and the bad set of plugins. Please repeat the + `Installing the Dependencies` section of this guide. + + - Advanced debugging: Incorrect video format + + If while running the advanced debugging you get the message: + + ``` + h265parse gsth265parse.c:1110:gst_h265_parse_handle_frame: broken/invalid nal Type: 48 Invalid, Size: 1073 will be dropped + ``` + + You have not set the format to `h264` in the `[[ cameras ]]` config while + using an E1 or Lumos. + + Change the `[[ cameras ]]` config to include `format = "h264"` and restart + neolink + + (If you are using another camera and you need to use h264 please let us + know so we can update this guide) + +- Something else + + If you still have problems open an issue on github and attach the + neolink log. You can save the log to file with the following command: + + ```bash + GST_DEBUG=3 ./neolink --config my_config.toml 2>&1 > neolink.log + ```