From b87f575ca55220a6d7066d6c96e6895ea4721e04 Mon Sep 17 00:00:00 2001 From: Pliable Pixels Date: Fri, 15 Mar 2019 09:27:24 -0400 Subject: moved dirs --- docs/_build/html/guides/FAQ.html | 987 +++++++++++++++++++++ docs/_build/html/guides/contributing-language.html | 289 ++++++ docs/_build/html/guides/desktop.html | 333 +++++++ docs/_build/html/guides/source.html | 468 ++++++++++ docs/_build/html/guides/validating-api.html | 331 +++++++ 5 files changed, 2408 insertions(+) create mode 100644 docs/_build/html/guides/FAQ.html create mode 100644 docs/_build/html/guides/contributing-language.html create mode 100644 docs/_build/html/guides/desktop.html create mode 100644 docs/_build/html/guides/source.html create mode 100644 docs/_build/html/guides/validating-api.html (limited to 'docs/_build/html/guides') diff --git a/docs/_build/html/guides/FAQ.html b/docs/_build/html/guides/FAQ.html new file mode 100644 index 00000000..fe38493e --- /dev/null +++ b/docs/_build/html/guides/FAQ.html @@ -0,0 +1,987 @@ + + + + + + + + + + + zmNinja FAQ — zmNinja documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+ + + + + + + + + + + + + + + + +
+ + + + +
+
+
+
+ +
+

zmNinja FAQ

+
+

What is the minimum supported version of ZoneMinder, Android and iOS?

+

You need a minimum of ZM 1.30.4 with APIs working. You may get it to run +in previous versions, but I don’t support them, so you are on your own.

+

Starting version 1.3.26 of zmNinja, only IOS 10+ and Android 5.0+ +devices are supported.

+
+
+

zmNinja Help

+

I’ve just started uploading instructional videos for zmNinja. I’ll add +more over time. See them +here

+
+
+

Asking for refunds

+

If you have bought the iOS version of the app, it doesn’t look like I +can process a refund anymore. If any developer knows how, please let me +know. Apple wants you to contact them directly using +this link.

+

For Android: If you’re not happy with zmNinja and have bought the app, +please send me an email with your +order id.

+

Note that depending on how long ago you made the order, I may not be +able to refund. Its not my policy - The app/play stores disable the +refund option. For example, I could not refund an app a user purchased 2 +years ago.

+

Also, please read Things you should own up +to

+
+
+

Things you should own up to

+
+

Read the app description

+

Both the Apple and Android stores have a clearly visible note on the app +description that it requires a working API for ZoneMinder. If you are +not willing to ensure the API works, please save yourself and me time. +I’m sorry this is the first post, but I get emails from too many +entitled/rude folks about APIs not working. Not my problem. Read below. +Breathe.

+
+
+

Try before buy

+

Some users legitimately look around for an option to try before they buy +and they are not savvy enough to download the +code and +compile +themselves. Fair enough. In that case, download the Desktop +version of +zmNinja. It’s free and is the same code as mobile. Make sure the desktop +version works before you buy the mobile version.

+

The reason I don’t have a “trial mobile version” is that I find the +process too complex using in-app-purchases and chose not to do it to +make life simpler for me. As a substitute, I do make the full code +available for free and offer a desktop binary version free too.

+
+
+

zmNinja doesn’t work. Actually, even ZoneMinder web console doesn’t work. You should fix this!

+

Yeah, look - I understand zmNinja won’t work if ZoneMinder web console +doesn’t work. That being said, I really don’t have time to help you +debug ZoneMinder issues. I only develop the app (zmNinja). If you can’t +set up ZoneMinder properly, please post your questions in the ZM +forum. You’ll find more qualified +people to help you. I don’t develop nor control ZoneMinder. It’s a +different set of folks. Now, I’ll help you, but only after you have +spent sufficient time trying your best and provide sufficient logs of +what you have done. Also remember, if you buy zmNinja, I’m happy to +refund it anytime - just send me an email.

+

In short, I don’t have the time to support ZoneMinder install issues - +sorry about that

+
+
+

zmNinja doesn’t work. Zoneminder works, but I have no idea why APIs don’t work. You should fix this!

+

Sigh. I don’t maintain ZoneMinder. I only develop the app. You need +to make sure ZoneMinder APIs work. ZoneMinder web console doesn’t use +APIs. Neither does zmView. zmNinja does. It says so in the description +of the app in the store. So feel free to fix your APIs, or ask me for a +refund. Just don’t whine to me, please, if your APIs are broken. I’m +not going to fix them for you, especially if you act like its not your +problem. I’m perfectly fine if you choose not to use my +app, which +is why I refund, anytime.

+
+
+

I can’t compile zmNinja, help me!

+

I put out the source code, so people who know how to compile are able to +do it themselves. I also hope this will encourage folks to PR changes +(though this has rarely happened). The problem however, is that +dependencies/libraries keep changing. I just don’t have the time to help +debug. If it happens to me, I’ll fix it. If it doesn’t I have very +limited time to remotely debug your setup issues. I’d much appreciate if +you figured it out on your own. Feel free to create an issue after +you’ve tried enough, but I can’t guarantee I’ll spend a lot of time on +source code compile issues.

+
+
+

How to report errors

+
    +
  • I don’t know why something is not working if you don’t provide +sufficient inputs. Start by creating a GitHub +issue and please +fill in the template correctly. If you don’t want to post debug logs +in the issue, email them +to me and mention in the issue you’ve emailed them (you can email by +going to logs screen and tapping on the envelope button (mobile) or +you can download logs (cloud icon, desktop version)
    • +
  • If zmNinja was working, but it stopped after you upgraded ZoneMinder +be sure to mention which version was working and which was not. In +this case, please make sure you have validated the APIs work
    • +
  • Before you create an issue, please make sure you have read the +sections on connection +issues +and +streaming +issues and Step 6 of +validating +APIs.
    • +
  • Its often hard to infer a problem especially when its due to some +unique apache/nginx mungling you might have done but haven’t told me +about it. In such cases, try and give me remote access to your ZM for +a day. Configure a limited user with just one monitor. It will save +hours of frustration (mostly on my side). Thanks
    • +
  • I have released the desktop version free - download it +here. Its +always easier to debug on the desktop version - give it a try. If you +hit Shift+Cmd/Ctrl+D it brings up a debug window - it helps debugging
    • +
  • Always tell me what your ZoneMinder & zmNinja versions are
    • +
  • If your app suddenly stopped working:
      +
    • Send me DEBUG logs of the app
      • +
    • tell me what changed (got to be something. You updated the app, +you upgraded ZM)
      • +
    • What exactly is not working?
      • +
    +
    • +
+
+
+ +
+

Connection/Authentication issues

+
+

General tips

+
    +
  • Disable server redirects like 302 and then try if using the mobile +app
    • +
  • To make sure there are no connection issues, launch your phone +browser and try to reach ZoneMinder. If that doesn’t work, neither +with zmNinja. Many users try to access ZoneMinder from a desktop +browser and/or on the same server it is running and forget the phone +is a different device!
    • +
  • Some phones need the SSL certificate installed in the device
    • +
  • Specific SSL settings can cause issues with Android or iOS
    • +
  • Don’t use funky/special characters in passwords - try changing it to +a complex password without funky characters and try
    • +
  • Use the wizard - I’ve seen many examples of typos when the user +thinks they don’t have a typo
    • +
  • If you are using basic authentication, make sure your credentials are +correct. A good way to test is to first disable basic auth and enable +it after you are sure things work without basic auth.
    • +
  • Please note zmNinja does NOT support Digest authentication. So please +don’t put in digest auth info when zmNinja asks for basic +authentication
    • +
  • Look at your ZM logs and zmNinja logs - they help isolate the problem
    • +
+
+
+

Server Redirects

+

If the Wizard fails to connect in the mobile app but works in the +desktop app, it may be that your server is sending redirects. +Unfortunately, the current mobile HTTP stack doesn’t handle cookies with +redirects well. Till this bug is fixed by the plugin author Wizard won’t +work. Note that if you are running ZM 1.32 or above, you can directly +enter your settings without using the wizard and it will work because it +will try and use the new ZM 1.32 login.json API first.

+
+
+

Self signed certs

+

A lot of people use self-signed certs. I’d strongly recommend you use +LetsEncrypt if you can. It’s free. That +being said zmNinja does support self signed certs. Make sure “Enable +Strict SSL” is off in Developer settings. You will need to restart the +app.

+
+
+

SSL settings

+

If you are getting SSL protocol/handshake errors in your logs, you +very likely have specific ssl settings enabled server side that your +device network stack does not support. Note that just because it works +with the device browser does not mean it will work with zmNinja as +zmNinja does not use the browser HTTP implementation in mobile devices.

+

One use reported that a setting of ssl_ecdh_curve secp384r1 in his +nginx config was resulting in zmNinja Android not being able to connect +to the server. Changing it to +ssl_ecdh_curve secp521r1:secp384r1:prime256v1; worked for him.

+

I’d strongly recommend you remove all special ssl settings except the +certificate and key file locations, make it work and then add the +settings back one by one and see what works/does not work.

+
+
+

Everything works when I use LAN IP, but I get “not authenticated” when I use WAN IP

+

This is likely happening if you use self signed SSL certs. If you are +using self signed certificated, you should make sure the “common name” +matches the hostname (or public IP) of the server you are installing ZM +in. If not, zmNinja’s SSL handshake will fail.

+

If you have used ‘make-ssl-cert’ or a similar tool that automatically +generates the cert for you, its very likely you have certificate that +uses the ‘unix hostname’ of your server. That will not work.

+

Assuming you are usin apache and have SSL enabled, here is how to +regenerate the certs (ubuntu specific, may need to tweak it for your +distro)

+

This will create a self-signed certificate/key pair and store it in +/etc/apache2/ssl (you may have to create that directory, or store it +elsewhere)

+
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/zoneminder.key -out /etc/apache2/ssl/zoneminder.crt
+
+
+

Next up, edit your apache ssl config (example +/etc/apache2/sites-available/default-ssl.conf) And add/modify the +following lines:

+
SSLCertificateFile /etc/apache2/ssl/zoneminder.crt
+SSLCertificateKeyFile /etc/apache2/ssl/zoneminder.key
+
+
+

restart apache

+
sudo service apache2 restart
+
+
+
+
+
+

Live streaming issues

+
+

Summary of Everything works, but I can’t see live feed

+

Please be diligent in reviewing this list. You’d be surprised how many +times I’ve had users tell me ‘they have checked this list’ only to find +out later they skimmed details.

+
    +
  • Please enable AUTH_HASH_LOGINS as well as set AUTH_RELAY to +“hashed”
    • +
  • You think your APIs are working, but they are really not. If you open +a browser and type in https://yourserver/zm/api/monitors.json and +you see some text on top followed by monitor data, your APIs are +not working. You need to search the forums and figure out how to +get rid of that text.
    • +
  • Your ZoneMinder live view from the web console doesn’t work either. +If this is the case, fix ZoneMinder first. Before you say “web +console works fine”, make sure you are running it from a different +computer from where ZM is running.
    • +
  • The phone/computer running zmNinja does not have access to your ZM +server. For example, many people test the web console on their LAN +but test zmninja on a WAN connection
    • +
  • Always try with the free desktop +version first. +Enable debug view by hitting Ctrl/Cmd+Alt+D and you can see debug +logs in the console view. I can’t emphasize enough how useful this +is.
    • +
  • Your cgi-bin setting in zmNinja is incorrect. Please run the +wizard. There are times when the wizard can fail. In those cases, +open up ZM web console, go to view the monitor and do an “Inspect +Source” in the browser. That will show you the cgi-bin link that you +can use in zmNinja.
    • +
+

For example:

+

In the above case my zmNinja cgi-bin setting is +https://myserver:myport/zm/cgi-bin

+
    +
  • You are using Basic Authentication. See +here
    • +
  • You have ‘multi-server’ configuration enabled and you have done it +wrong. Go to ZM Web Console->Options->Servers - if you see any +entries there and you don’t know what multi-server is, or you don’t +use it, please disable multi-server
    • +
  • When trying to view live images, look at your webserver error logs +- example Apache’s error.log - see any image/jpg errors? That +means you are missing libraries
    • +
  • You have set up a multi-server install of ZM without knowing you did +See here
    • +
  • Look at zmNinja, ZoneMinder and web server error logs at the time of +error - one of them should give more clues. Please send me all the +logs if you ask for help
    • +
  • Read the set of notes below
    • +
+
+
+

General note

+

To debug streaming notes, always try with the free desktop version +first. When trying to stream simultaneously look at the debug logs of +zmNinja (Ctrl/Cmd+Alt+D in desktop build, console and/or network +tab) and your webserver error logs.

+
+
+

I can’t see stream: And I can’t see streams in ZoneMinder webconsole either

+

Check if streaming works in the web interface. If it does not work, +zmNinja won’t work either. Fix ZM first

+
+
+

I can’t see streams: I use basic auth

+

Starting Chrome v59, the browser changed basic credential behavior. The +issue report is +here. +Here is the core issue: zmNinja constructs URLs as +http://user:password@server when you have basic auth (and starting +v1.3 uses the Authorization header). However, since images are +rendered using <img src> there is no option but to put in a +user:password in the URL. Chrome allows this format for direct +requests (such as API calls) but will strip out the user:password +part for embedded requests (like <img src=""> tags inside a page). +So what happens is your APIs work, but you won’t see images. There is a +reason why Chrome does this - its bad to pass on a user :password in a +URL as its clear text (even if you are on HTTPS, as its in the URL). As +I said earlier, The right way to do this is to replace the +user:pass with an Authorization header but there is no way to do +that with images that are rendered with <img src> (There are several +plugins that attempt to do this, but don’t work with streaming MJPEG +images). Bottom line, this is a problem for apps like zmNinja and it +affects you.

+

How this affects you: * If you are using HTTP Basic Authentication

+

Then your images won’t show.

+

Possible Workarounds: * Configure your web server to skip basic +authentication for nph-zms URLs * If you are using a ReverseProxy, +you can insert the authorization header inside the apache proxy * +Disable HTTP Basic auth for now * Downgrade Chrome

+
+

Skipping auth for nph-zms URLs

+

Here is what I’ve used that works with basic-auth. This requires a basic +auth portal login and once logged in allows skipping of image URLs (the +idea comes from Adam Outler - he +uses a different approach using reverse proxies, which I link to later)

+
  # this configuration assumes your server portal is server:port/zm
+  # and cgi-path is /zm/cgi-bin. Please change it to your specific environment
+  # Also requires Apache 2.4 or above
+
+<Location />
+      SetEnvIf Request_URI ^/zm/cgi-bin/ noauth=1
+      SetEnvIf Request_URI ^/zm/index.php noauth=1
+      AuthType Basic
+      AuthName "Auth Required"
+      AuthUserFile "/etc/apache2/.htpasswd"
+      <RequireAny>
+          Require valid-user
+          Require env noauth
+      </RequireAny>
+</Location>
+
+
+
+
+

Authorization with a ReverseProxy

+
+
Simple starter
+

STEP 1: Enable “Append basic auth tokens in images” option in +zmNinja->Developer Settings and save. What this does is that image URLs +will append a “basicauth” token parameter with your basic authentication +credentials. This token can then be parsed by Apache and inserted as a +valid Authorization header. Don’t enable this option if you are not +using HTTPS because the request-URI will be transmitted without +encryption and it will contain your basic auth credentials, encoded in +base64, which is trivial to decode.

+

STEP 2 (Apache): Use mod_rewrite and mod_header to convert the +token into an authorization in your Apache config. Add this to the +relevant section (VirtualHost or others)

+
RewriteEngine on
+RewriteCond %{QUERY_STRING} (?:^|&)basicauth=([^&]+)
+RewriteRule (.*) - [E=QS_TOKEN:%1]
+RequestHeader set Authorization "Basic %{QS_TOKEN}e" env=QS_TOKEN
+
+
+

STEP 2 (Nginx): Thanks to user [@ysammy](https://github.com/ysammy)

+
location /zm/cgi-bin/nph-zms {
+   proxy_pass http://<IP>:<PORT>/zm/cgi-bin/nph-zms;
+   proxy_set_header Authorization "Basic $arg_basicauth";
+ }
+
+
+
+
+
A more complete and more secure option
+

User Adam Outler has contributed the +following process: see +HERE. +Adam also has this to say about why proxies should be recommended for +HTTPS enabled ZoneMinder instances:

+
+
A proxy server should be on the list of recommendations for +Zoneminder. HTTPS requires processing to encrypt and decrypt. This +takes processor cycles away from Zoneminder’s recording. Since HTTPS +is now basically a requirement, there should be a page dedicated to +proxy, https, auth, and their nuances. I just picked up 2-4K cameras +and processing suddenly became an issue :).
+
+
+
+
+

I can’t see streams: Multi-server is enabled

+

The chances are very high that you have enabled ZoneMinder’s +Multi-Server +option and you entered something like localhost in server settings. +DON’T. You can’t enter localhost. If you are not using multi-server, +remove any server settings. If you are using multi-server, you need to +put in a valid server IP or hostname, not localhost. BTW, if you did +put in localhost you will note that your ZM web console also won’t +work if you try to launch your browser on a different machine from where +ZM is running.

+
+
+

I can’t see streams: you have cgi-bin issues

+
    +
  • Try to use the wizard. If it fails,
    • +
  • Go to zmNinja settings and fix your cgi-bin path. the automatic path +that is filled in won’t work. Here is a hint, go to +zoneminder->options->paths and check the value of the cgi-bin path - +your zmNinja path will be “base path of your server” + cgi-bin path.
    • +
+
+
+

zmNinja montage does not seem smooth - feeds seem a little delayed compared to ZM console

+

zmNinja does not use nph-zms to display live feeds in montage. This +is because Chrome only allows a maximum of 6 connections per (sub)domain +which means you can’t have more than 6 active TCP connections to a +single domain at the same time. This also means that you can’t display +more than 6 monitors together. To avoid this, I use the zoneminder +“snapshot” feature that displays a still from the monitor and then +refresh it every X seconds (by default X=2 unless you switch to low +bandwidth mode. You can change X in developer settings)

+

That being said, starting v1.3.0 of zmNinja onwards, I now support +multi-port (available in ZM 1.32 onwards) that lets you stream as many +monitors as you need. Read +this +post for more details.

+
+
+ +
+

Other misc. issues

+
+

I suddently see an error message saying I need to enable ZM_AUTH_HASH_LOGINS. This wasn’t there before

+

Yes. Starting 1.3.027 onwards, due to a new UI web rendering engine that +enforces CORS, I’ve had to change my strategy on how network calls are +made. Briefly, on mobile devices, I now use a native HTTP stack and not +the browser HTTP stack. However, images are rendered using the browser +HTTP stack which causes this message. In short, you need to enable it, +and restart ZM.

+
+
+

zmNinja 1.2.515 and beyond says “Need API Upgrade” for the 24hr review feature. What does that mean?

+

You need to update an API file in Zoneminder server. ZoneMinder folks +haven’t yet (as of Apr 2018) made a release with that API change. To do +it manually,simply replace your EventsController.php (typically in +/usr/share/zoneminder/www/api/app/Controller) with this +one.

+
+
+

I upgraded ZoneMinder to 1.30.2 or above and zmNinja stopped working!

+

ZoneMinder changed API packaging with ZM 1.30.2 and above. You will have +to read your distro notes on how to properly update. Read +this +thread. Before you think zmNinja is the problem, make sure your APIs +are +working. +Summary of reasons why zmNinja might have stopped working: - You did not +check if your APIs are working after the upgrade - You did not upgrade +properly (just updating the ZM package without following distro +instructions with ZM is not sufficient) - You are missing some key +CakePHP modules, likely php5-apc which would have been installed if +you read all the package instructions. You can install it manually - You +might need to restart your system after upgrading (properly)

+
+
+

I am running ZM on a custom port. zmNinja is unable to reach my ZoneMinder server but I tried on a regular browser (Firefox/Opera/IE) and it I can reach it

+

zmNinja on Android and Desktops uses an embedded chrome browser. Chrome +marks certain ports as “unsafe” and won’t allow connections to go out. +The list of ports to avoid are +here

+
+
+

The Montage screen is causing issues with my ZM server - I get connection timeout issues or MySQL connection problems

+
    +
  • zmNinja uses a different approach to display montage than ZoneMinder. +In zmNinja montage screen, I display a snapshot of each monitor and +refresh it every few seconds. This results in many short TCP +connections constantly being opened and closed. The reason I have to +do this is Chrome only allows 6 connections to a domain, which means +if I don’t keep terminating TCP connections, I won’t be able to show +more than 6 monitors. Each time I open a new TCP connection for a +snapshot, the ZM backend invokes mySQL to authenticate the request. +You will need to increase mySQL max_connections in my.cnf if +you are facing time_wait/timeout issues.
    • +
+
+
+

The app works great - except it doesn’t work on ONE Android phone - works in others!

+

zmNinja uses an embedded chrome browser in its app. If you have safe +browsing enabled, it may affect zmNinja. However, if you are facing this +problem, its likely you can’t access ZM from a mobile web browser +either. The problem that might be occurring is that zmNinja is trying to +reach your ZM server and your settings prohibit it from reaching ZM, so +it fails. See +this +discussion

+
+
+

APIs are not working ! ZM console works fine.

+

Read +this

+
+
+

I’m using mocord/record and I don’t see events without alarms

+

Tap on the “…” menu option and toggle “Show all events”. By default, +it shows events with at least one alarm frame

+
+
+

Taking snapshots or downloading videos don’t work in Android

+

If you are unable to download/save, look at your logs. If you see +something like +"exception":"java.security.cert.CertPathValidatorException: Trust anchor for certification path not found." +, chances are you are using self-signed certs. You need to install the +certificate on your phone. Installing is as easy as emailing yourself +the “.crt” file and tapping on it from your device to install it. In +general, both Apple and Google have been incrementally tightening rules +for self signed certificates - they generally discourage usage of such +certs and over time both Chrome (Android) and WkWebView (iOS) have added +new restrictions/checks which affects usage.

+
+
+

Pan/Tilt/Zoom doesn’t work

+

Tilt/Zoom/Presets support has not been added. But for this to work, PTZ +needs to work in ZM first. Once it works in ZM, try it in ZMNinja. Also +note that you may need to disable CSRF in your Options in ZoneMinder - +it seems to cause all sorts of issues.

+
+
+
+

What is this Event Server?

+

The Event Server is a contribution I made to ZoneMinder that adds a +daemon to the existing list. It listens for new events using shared +memory (aka very efficient) and then sends notifications of events to +listeners (you can write your own app that listen as well as use +zmNinja). This is a chapter on its own, and I have a dedicated +page/project for this +here. I’d encourage +you to install and use it - its very nice.

+
+

It looks like you allow me to modify the frequency of push notifications. Very cool - will it send me all events that I missed if I make the frequency of a monitor event push to say, 600 seconds?

+

Nope. It only sends the latest events. What it does is before sending +push notifications, it checks if the last time a push was sent for this +monitor is < the time you specified. If it is, it does not send. That’s +all.

+
+
+
+

Is zmNinja free?

+

The source code is free, grab it, compile it, use it. The desktop ports +are free as of today. I may charge for it some day. The mobile ports are +in Appstore/Playstore for a fee.

+
+
+

Who are the developers behind this?

+

Me.

+
+
+

The code needs improvement

+

You are being nice. I know the code is terrible. I’m not a coder by +profession. This was my first project to learn how to write a mobile +app. So the app evolved from no knowledge to some knowledge. It +comprises of terrible to passable to reasonable code. There is a reason +why my profile says what it says. +But hey, if you can improve it, please PR!

+
+
+

Is zmNinja an official ZoneMinder product?

+

No. But the ZM developers are amazing people who have been very helpful.

+
+
+

I want to donate money

+

You could either donate to to +Zoneminder or donate +to zmNinja. Donations +to ZoneMinder don’t contribute to zmNinja, but the ZoneMinder devs will +benefit from it, which is fine too.

+
+
+

How does zmNinja use my personal data?

+

Please read +this

+
+
+

I want to donate time/expertise/code

+

Great. Make sure you read the +license +, read the contributing +guidelines +and if it works for you, happy to see what you’d like to do.

+
+
+ + +
+
+ +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/guides/contributing-language.html b/docs/_build/html/guides/contributing-language.html new file mode 100644 index 00000000..bc8eff91 --- /dev/null +++ b/docs/_build/html/guides/contributing-language.html @@ -0,0 +1,289 @@ + + + + + + + + + + + Contributing a new language — zmNinja documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+ + + + + + + + + + + + + + + + +
+ + + + +
+
+
+
+ +
+

Contributing a new language

+

If you are familiar with using git, I’d prefer if you follow the Pull +Request process +here.

+
+

Adding a new language

+
    +
  • Languages translations are available +here
    • +
  • To contribute a new language, add a new locale-xx.json (where +xx is your language code).
    • +
  • Ideally, you should also provide a language translation for the +zmNinja help file inside +lang/help
    • +
+

The best way is to simply look at an existing language translation and +follow the same model for yours. If any language translation keywords +are missed, it will fallback to English.

+
+
+

Main Language file

+
    +
  • Make sure there is no comma after the last element
    • +
  • Comments are not allowed
    • +
  • Make sure you don’t add ellipsis “…” anywhere, they are added to +messages in code when needed
    • +
  • After you complete the translation file, do the following:
    • +
+

(replace -it with the language you are working on)

+

python ./checklang.py -f locale-it.json -b

+

This validates your JSON file, makes sure all keys are in sync with -en +and if valid, creates pretty-locale-it.json. If you are sure it looks +good,

+

python ./checklang.py -f locale-it.json -b -o

+

This validates your JSON file,makes sure all keys are in sync with -en +and if valid, OVERWRITES your local file with a pretty formatted +version, which is what you should PR

+
+
+

Translating Help language file

+
    +
  • Located inside lang/help
    • +
  • Please be careful not to mess up the html tags, please only focus on +text translation
    • +
+
+
+

How to recognize a new language:

+

(This is only for zmNinja developers. Not relevant for language +translators) * Modify languages array in NVR.js (look for “var +languages”) * register language glob code in app.js - make sure its +added to array list and mapping (look for registerAvailableLanguageKeys)

+
+
+ + +
+
+ +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/guides/desktop.html b/docs/_build/html/guides/desktop.html new file mode 100644 index 00000000..7a049bd8 --- /dev/null +++ b/docs/_build/html/guides/desktop.html @@ -0,0 +1,333 @@ + + + + + + + + + + + Desktop port tips — zmNinja documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+ + + + + + + + + + + + + + + + +
+ + + + +
+
+
+
+ +
+

Desktop port tips

+
+

Scope

+

This page is dedicated to the Desktop version of zmNinja and tips & +tricks

+
+
+

Command Line parameters

+

The following command line parameters are supported:

+
--path=<dir>  - starts zmNinja and stores user profile information to that directory.
+                This allows you to switch between different user settings.
+
+--fs          - starts zmNinja in full screen mode
+
+
+
+
+

Multiple instances

+

It is actually possible to launch multiple instances of the same desktop +app from command line. This allows you to watch different servers at the +same time as well as use multiple monitors. I strongly recommend you use +unique --path arguments with each instance because otherwise one +instance will conflict with another.

+

So lets say you want to run 2 copies of zmNinja at the same time:

+
mkdir -p /path/to/instance1
+mkdir -p /path/to/instance2
+
+
+

And then:

+
# for linux
+zmninjapro-1.3.22-x86_64.AppImage  --path=/path/to/instance1
+zmninjapro-1.3.22-x86_64.AppImage  --path=/path/to/instance2
+
+#for OSX. Note the -n is critical to launch a new instance
+open -n ./zmninjapro.app --args --path=/path/to/instance1 &
+open -n ./zmninjapro.app --args --path=/path/to/instance2 &
+
+
+
+
+

Hotkeys

+

The following hotkeys are supported while the app is running:

+
[Cmd/Ctrl] + L         -> Lock app (if pin code is being used)
+[Cmd/Ctrl] + Shift + F -> toggle between full screen and windowed mode
+[Cmd/Ctrl] + Shift + D -> opens the debug window.
+                        Super useful to see what is going on,
+                        especially when things don't work
+
+
+
+
+

Keyboard bindings

+

Live Monitor View (single view, not montage):

+
Arrow Left  -> move to previous monitor
+Arrow Right -> move to next monitor
+Esc         -> remove live view
+P           -> toggle PTZ
+
+
+

PTZ Operations to move (PTZ should be toggled to on first):

+
Q W E  -> UpLeft, Up, UpRight
+A S D  -> Left, Home,Right
+Z X C  -> DownLeft, Down, DownRight
+
+
+

Event Footage View:

+
Arrow Left  -> move to previous event
+Arrow Right -> move to next event
+Enter       -> play the event if in snapshot mode (shows red play button)
+Esc         -> remove event footage view
+
+
+

Timeline:

+
Arrow Up    -> Zoom In
+Arrow Down  -> Zoom Out
+Arrow Left  -> Pan Left
+Arrow Right -> Pan Right
+Esc         -> Fit timeline back to view (reset)
+A           -> Previous Day
+D           -> Next Day
+
+
+
+
+

Desktop data storage locations

+

User data is typically stored in the following locations: * +%APPDATA%/zmNinjaDesktop for Windows, * +$XDG_CONFIG_HOME/zmNinjaDesktop or ~/.config/zmNinjaDesktop for +Linux, and * ~/Library/Application Support/zmNinjaDesktop for OSX

+

To completely remove the app, you may want to delete both the app +bundle/binary and these locations as applicable on your system

+
+
+ + +
+
+ +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/guides/source.html b/docs/_build/html/guides/source.html new file mode 100644 index 00000000..ce53f606 --- /dev/null +++ b/docs/_build/html/guides/source.html @@ -0,0 +1,468 @@ + + + + + + + + + + + Building from Source — zmNinja documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+ + + + + + + + + + + + + + + + +
+ + + + +
+
+
+
+ +
+

Building from Source

+

NOTE If you want to run it on your desktop, you can directly +download desktop binaries +here +and if you want it for Android/iOS you can get from the play/appstore. +This is only for those who want to run from source.

+
+
Note: If you are building from source, you are mostly on your own. I +have very limited time to debug environment differences/package +differences between what I have and what you may have. I’m not a +nodejs/grunt etc expert and stuff seems to change all the time.
+

Version note: The code is compiled using the following versions of +tools. If you are using newer versions of ionic the code may not +compile - I don’t have the time to upgrade yet. Finally, if you choose +to go the source route, I expect you to spend a lot of time yourself +debugging first before you create an issue. Even if you do create an +issue, I have very limited bandwidth to debug source compilation issues +for you. Thanks.

+

Output of ionic info

+
Ionic:
+
+   ionic (Ionic CLI) : 4.5.0 (/usr/local/lib/node_modules/ionic)
+   Ionic Framework   : ionic1 1.3.5
+   @ionic/v1-toolkit : 1.0.19
+
+Cordova:
+
+   cordova (Cordova CLI) : 8.1.2 (cordova-lib@8.1.1)
+   Cordova Platforms     : android 7.1.4, ios 5.0.0
+   Cordova Plugins       : cordova-plugin-ionic-keyboard 2.1.3, cordova-plugin-ionic-webview 2.2.0,
+(and 30 other plugins)
+
+System:
+
+   Android SDK Tools : 26.1.1 (/Users/pp/Library/Android/sdk/)
+   ios-deploy        : 2.0.0
+   ios-sim           : 7.0.0
+   NodeJS            : v8.11.2 (/usr/local/bin/node)
+   npm               : 5.6.0
+   OS                : macOS Mojave
+   Xcode             : Xcode 10.1 Build version 10B61
+
+
+
+

Install Dependencies - needed for all platforms

+
+

Install NodeJS

+

Install NodeJS from here. As of +Dec 2018, I’m using Node v8.11.2. I use +n to manage node versions and switch +between them.

+
+
+

Install cordova, ionic, and bower

+
npm install -g cordova ionic bower
+npm install @ionic/v1-toolkit --save-dev
+
+
+

And some more:

+
npm install -g gulp
+npm install node-sass
+npm install async
+npm install jshint
+
+
+

(Note you may need to do sudo depending on how your system is set +up. It’s better you +don’t, +but if you must, well, you must)

+

If you get a newer version, you should adjust your cordova version to +the mentioned version above in order to be able to successfully compile +zmNinja. To change the version you can follow these instructions: +change cordova +version

+
+
+
+

Download zmNinja

+
git clone --depth 1 https://github.com/pliablepixels/zmNinja.git
+
+
+
+
+

Configure build configure zmNinja and get all required plugins

+
cd zmNinja
+npm install
+bower install
+ionic cordova platform add android (or ios)
+cordova prepare
+
+
+
+
+

Making an iOS build

+

Note: You need to be doing this on a mac, with Xcode and the SDK +installed. You also need to have your developer certificates/etc. (I am +not going to detail this out - there are many internet resources on +this)

+

There are a few steps you need to take to get the iOS build working for +the first time. If you don’t do this, you may get a compilation error +that says ld: library not found for -lGoogleToolboxForMac

+
cd platforms/ios
+pod install
+
+
+

This does not produce an iOS ready ipa. What you need to do then is to +open platforms/ios/zmNinja.xcworkspace in Xcode, and run.

+

To compile a debug build for iOS from command line, from zmNinja project +root: First edit ./build-auto.json and change the +developmentTeam id to yours. Then:

+
./build_ios.sh
+
+
+

To compile using XCode, open platforms/ios/zmNinja.xcworkspace - You +need to use “Legacy Build” system if you are on XCode 10+. You can +change this in XCode File->Workspace Settings and then build usual. +Also switch to the Capabilities tab and make sure “Remote Notifications” +is on in Background Modes and in iCloud section, Key-Value storage is +enabled. If you see a “Fix issue” there, clicking on that button +resolves everything.

+
+
+

Making an Android build

+

Note that you need the Android +SDK installed and +configured properly for this to work.

+

From the zmNinja project root:

+
./build_android.sh --debug (or --release)
+
+
+

If this complains of missing SDKs, you need to install the SDK version +it requests This should produce an APK file. To install it on your phone +over adb, you’d do something like

+
adb install -r debug_files/android-debug.apk #if you did --debug
+or,
+adb install -r release_files/zmNinja.apk #if you did --release
+
+
+
+
+

Making a desktop build

+

I use electron to build the desktop app.

+
+

For versions 1.3.018 and beyond

+

I’ve migrated to using +electron-builder +to automate the build process better.

+
+

Make sure you have all the dependencies

+

Typically, just running

+
npm install
+bower install
+
+
+

Should have installed everything. Validate by checking you have +electron installed by invoking it on the command line

+

You now have the following options:

+
npm run dist-all # builds linux, mac and windows packages
+npm run dist-mac # only builds mac packages
+npm run dist-lin # only builds linux packages (32bit, 64bit, arm)
+npm run dist-win # only builds win packages (32bit, 64bit)
+
+
+

Your packages will be created in the dist folder

+
+
+
+

Set up desktop dependencies

+
npm install -g electron
+npm install -g asar
+
+
+

Make sure electron is installed. You should be able to do a +which electron

+

Also make sure unzip and wget tools are installed in your +system.

+
+
+

First time setup

+

If this is the first time you are building a desktop version, you need +to download electron images for various platforms. There is a helper +script called prepare_desktop.sh that you can run. This creates a +directory called desktop inside your zmNinja directory. It currently +downloads all supported platforms.

+
./prepare_desktop.sh
+
+
+

This will download a bunch of files. If completed successfully, you can +proceed to the next step.

+
+
+

Make the desktop build

+

Once you are done with prepare_desktop.sh, you can do a +./make_desktop.sh. This will actually build images for all +platforms.

+
+
+

Running desktop builds

+

cd into the desktop directory and run whichever port you want

+
+
+

Subsequent builds

+

You need to ./make_desktop.sh each time you make changes.

+
+
+
+

Troubleshooting

+

Lots of things can go wrong. * Please make sure you don’t post issues +about why your own build is not working - please figure it out * Look +carefully at error messages

+
+
+ + +
+
+ +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_build/html/guides/validating-api.html b/docs/_build/html/guides/validating-api.html new file mode 100644 index 00000000..fd0eb148 --- /dev/null +++ b/docs/_build/html/guides/validating-api.html @@ -0,0 +1,331 @@ + + + + + + + + + + + Validating APIs — zmNinja documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+ + + + + + + + + + + + + + + + +
+ + + + +
+
+
+
+ +
+

Validating APIs

+
+

Please make sure you go through this before you wonder why zmNinja is not working.

+
+
Assumption: Your ZM server is accessible at http://server/zm -> +replace this with your actual path
+
+

Make sure ZM APIs are working:

+

(Note - nginx users, if you are facing API issues, please see if this +page +helps)

+
    +

  • Step 1: Open up a browser

    +
    • +

  • Step 2: Log into ZM

    +
    • +

  • Step 3: Open another tab in the same browser (IMPORTANT: Has to +be from the same browser you logged into ZM)

    +
    • +

  • Step 4: Type in http://server/zm/api/host/getVersion.json –> you +should see a response like:

    +
    {
+"version": "1.30.0",
+"apiversion": "1.0"
+}
+
    +
    +

    version/apiversion may be different. If you don’t see such a +response, your APIs are not working

    +
    • +

  • Step 5:make sure you can see monitors and events:

    +
    • +
+

Type in http://server/zm/api/monitors.json –> you should see a +response like:

+
{
+    "monitors": [
+        {
+            "Monitor": {
+                /*lots of additional details*/
+            },
+            /*more monitor objects if you have more than one*/
+        }]
+}
+
+
+
    +
  • Step 6: (If you find your APIs show ok, but zmNinja has issues)
    • +
  • Open a browser, log into ZM
    • +
  • Open a new tab, enter http://server/zm/api/host/getVersion.json
    • +
  • Now, right click and do a View Source in your browser (different +browsers may have different names for it). This brings up a full +source code view of the page. Do you ONLY see the JSON output or do +you see gobs of HTML on top like <pre class= and lots of cake +related messages? If you do, you need to fix it.
    • +
+

if you find the page empty, your APIs/permissions have a problem. Please +post in the ZM forums (please DON’T contact me first as its not a +zmNinja bug)

+

Type in http://server/zm/api/events.json –> you should see a +response like: (this list may be an empty set if you don’t have events +but you will still see the {"events":[]} text - if you find the page +empty, your APIs have a problem. Please post in the ZM forums (please +DON’T contact me first, as its not a zmNinja bug)

+
{"events":[{"Event":{ /* many more details */ }}]}
+
+
+

Top reasons why monitors and events API returns blank while getVersion +works: * You don’t have monitor/event view permissions allocated to +the user * You have an invalid camera definition (happens sometimes +when you remove and re-add cameras) * If you are using non UTF8 +characters in your monitor names/zone names this can cause issues. Edit +/usr/share/zoneminder/www/api/app/Config/database.php (assuming ZM +is in /usr/share) and make sure 'encoding' => 'utf8' is +uncommented (remove //) around line 74. I’ve submitted a +patch +but till its merged, you might have to do it manually.

+
+
+
+

zmNinja API notes:

+
    +
  • Please make sure the user credentials you use has:
    • +
  • view or edit access to monitors
    • +
  • view or edit access to streams
    • +
  • view or edit access to system
    • +
  • If you are accessing zmNinja remotely, make sure you first access ZM +remotely from your desktop browser, ensure it works and then use the +same DNS/IP for zmNinja
    • +
+
+
+ + +
+
+ +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file -- cgit v1.2.3