Versions Compared

Version Old Version 6 New Version Current
Changes made by

Roselle B Dela Fuente (Unlicensed)

Espen Nersveen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Installing the LIPI CLI Tool

Download the CLI tool

Code Block
wget https://storage.mazemap.com/lipi/latest/lipi

Make the file executable (root privilege required)

Code Block
chmod +x lipi

Add lipi command to your path. (root privilege required)

Code Block
mv lipi /usr/local/bin/

Complete the installation (one time setup of API key and installation folder)

Code Block
lipi --setup
Initiating setup
Setup already complete. Reconfigure (y/n): y
Mazemap API key: <input your API key from Map Editor here>

Putting in your API key:

a. Go to Map Editor and navigate the Indoor Positioning menu

...

b. Click the LIPI Configuration

...

c. Expand the LIPI configuration and click on “Generate”. You can copy this key and paste it on your SSH

...

When you have already pasted the API key as shown above, you will get a new question regarding the name of your new folder in the field as shown below. (E.g, “lipi-install” or any intuitive name).

Code Block
Installation folder: <input directory name here>

Once you have successfully installed the tool we use to install and set up the LIPI correctly, you will get the following message.

Code Block
Saving config: OK
Installing cron: OK
Setup complete

Usage

Download and install latest lipi

(requires MazeMap api key and internet access)

Code Block
languagebash
lipi --install latest

Note: If this is the first installation, the tool will also download the configuration
file from MazeMap.

Run status check

Code Block
languagebash
lipi --status

Run status check, and report to MazeMap

(requires MazeMap api key and internet access)

Code Block
languagebash
lipi --status report

List available lipi versions

(requires MazeMap api key and internet access)

Code Block
languagebash
lipi --list-available

Download and install specific version of lipi

(requires MazeMap api key and internet access)

Code Block
languagebash
lipi --install 1.0.1

Install from local source

Code Block
languagebash
lipi \
    --install 1.0.1 \
    --lipi-path /path/to/lipi.zip \
    --config-path /path/to/config.json

Install from MazeMap, using custom configuration file

Code Block
languagebash
lipi \
    --install latest \
    --config-path /path/to/config.json

Update config of running lipi

(requires MazeMap api key and internet access)

Code Block
languagebash
lipi --update-config

Update config of running lipi, using custom configuration file

(requires mazemap api key and internet access)

Code Block
languagebash
lipi --update-config \
    --config-path /path/to/config.json

List installed lipi versions and see which one is active

Code Block
languagebash
lipi --list

Activate a previous installation

Code Block
languagebash
lipi --activate [copy and paste a value from the list of installed versions]

Reconfigure running LIPI

Reinitialize the current configuration with new variables.

Code Block
languagebash
lipi --reconfigure

What happens during install and updating

  • If the MazeMap api key is set, the tool can download new versions of lipi and
    the configuration file from MazeMap servers.

  • After running initial --setup, the tool will install a cron task which regularly
    runs the command lipi --status report. This will send lipi health data to MazeMap
    on a regular basis so that we can provide a better level of service to you. This is
    only installed if the MazeMap API Key is set during setup. If this is not installed
    we can not help debugging an installation, and we will not be able to help users
    if they have trouble accessing the LIPI service. See Run status check, and report to MazeMap
    to see what is reported to MazeMap.

  • When installing a new version of LIPI, the update tool will prefer to use the
    configuration files of the currently running LIPI version. This can be overridden
    using the --config-path flag or by running --update-config before running
    --install.

  • Every --install and --update-config creates a new installation version. This
    is done to allow switching between new and previous installations or configurations
    at will. If something goes wrong, a previous version can be activated using
    --activate. The installation or update process will activate the previous version
    if the new version can't be started or seem unresponsive (if --status does not
    show a fully healthy installation).

Manual fixing:

  • --setup stored values in a file params.txt. Running --setup again will overwrite it.

  • A LIPI service has a config.json in its installation folder, which can be copied,
    edited and used using --config-path, if needed.

  • The folders under lipi installation path are self contained and can be deleted at will.
    Just make sure to not delete the running version. Use --list or --status to see which
    version is running.

  • LIPI is started using systemctl. Status and control of that service is available.
    systemctl [status|start|stop|restart] lipi.service.

Internal README

Local development

Build and start test docker container:

Code Block
./test.sh

Docker container contains following folders:

/updatetool - mazemap-gerrit/positioning/updatetool/

/lipi-sources - contains set of lipi test installations and an empty config.json

/mockservice - contains files needed to start the mock service

Packaging

Start test docker container and run:

Code Block
languagebash
./package.sh

Produces updatetool/bin/lipi

Testing with mock lipi installation

Following commands are run from inside test docker container.

Code Block
languagebash
# Starts a service on port 443 which answers 200 on localhost:443/shallow and localhost:443/deep.
# This will allow the health checks to complete even though there's no lipi service running.
./start-mock-server.sh

# run commands on python src:
python src/updater.py --help

# run commands using packaged executable
bin/lipi --help

SUMMARY

This summary contains commands that are useful when setting up the LIPI server.

The config file that is used is under the /srv folder use command cd to open folder and ls to read what is in the folder.

...

Action

...

Command

...

Comment

...

Start LIPI server

...

sudo systemctl start lipi

...

Stop LIPI server

...

sudo systemctl stop lipi

...

Restart LIPI server

...

sudo systemctl restart lipi

...

Status of LIPI server

...

sudo systemctl status lipi

...

Check the lipi log

...

journalctl -u lipi -n 200 -f

...

Create a new command line user in CMX

...

cmxos apiserver user add [the_username] [the_password]

...

Update lipi

...

Download the new lipi 

Make sure that the file is executable by typing:
chmod +x upgrade.sh
Then run the command:
sudo ./upgrade.sh

...

open and update the config file

...

sudo nano config.json

...

view the config file

...

cat config.json

...

Move a file from one location to another

...

mv <start location> <end location> 
e.g. mv /home/cygate/config.json /srv/

...


We now have a simplified way of installing the LIPI indoor positioning software using our new CLI Tool. This is a comprehensive document and is divided into 5 parts as shown below.

Please note that you will still need to involve someone who has access to the LIPI server, has experience with SSH and Linux, and preferably has access to CMX GUI. Let us make sure that our system is ready for our positioning system by checking these prerequisites beforehand and complying with them.

Note: If you are planning to install a LIPI that does not have internet connection, please refer to https://mazemap.atlassian.net/l/c/1eY8xdGE

Note: To install LIPI for DNA Spaces please refer to https://mazemap.atlassian.net/wiki/spaces/MCSH/pages/981762065/HOW+TO+INSTALL+THE+NEW+AND+IMPROVED+LIPI+for+DNA+Spaces

PREREQUISITES for the LIPI Installation

Requirements for the LIPI server

  • Can be virtual or physical, does not matter.

  • Docker installed

  • Access to internet

Requirements for the network

  • Open port 443 from LIPI server to CMX (https for API).

    • Open port 443 from all wireless clients to LIPI (https for position requests).

    • Open port 443 from all wireless clients to MazeMap server.

    • Traffic from Wireless Clients to LIPI must not pass through NAT.

Requirements for the CMX 

If the lipi is to be configured to use DNA-Spaces (MazeMap Cloud Positioning) then ignore this part of the doc

  • CMX set up with Location services activated and sufficient licenses.

    • Building maps, with correct map scaling and a minimum of 3 GPS markers per floor need to be set up on Cisco Prime, exported and imported into CMX.

      • GPS markers should use coordinates created using MazeMaps own map. MazeMap provides a tool for generating these. You can find the POI inspector-tool here: https://debug.mazemap.com/

    • Access points must be placed correctly (within a meter of actual location) in the maps in Cisco Prime.

    • Enable the API server

      Code Block
      cmxos apiserver enable
cmxos apiserver restart

    • CMX GUI user for MazeMap with Full Read Only privileges set up on CMX.

    • CMX CLI API user with full Read and API access. Both CMX GUI and CLI users should have the same username/password
      To create a CMX CLI user ssh into your CMX and run the following command:

      Code Block
      cmxos apiserver user add

You will be asked to type in a username and password for the user - use the same username and password as you used for the GUI user.

Image Added

Dependencies

In order to upgrade the LIPI you will need the following:

  • SSH access to the LIPI server.

  • Access to CMX GUI (browser) and CLI (terminal).

  • A device that is connected to the WiFi network that is used for positioning purposes. This requires you being on site at the campus and using public wifi network

  • Pre-installed java in the server openjdk-8-jre-headless

  • Access to Map Editor in MazeMap https://admin.mazemap.com/

  • LIPI 4.1.1 software update tool that can be downloaded from here: https://storage.mazemap.com/lipi/latest/lipi

Information the customer has to send to MazeMap

  • Private IP-address of the LIPI server (The one WiFi clients will connect to the LIPI with; in IPv4 or IPv6 formats). Used to set up DNS Record showing domain name *.mazepos.com

  • Public IP address/es range/s for all WIFI-clients (the NAT-devices' IP-address if in use). Used for network configuration setup

  • CMX Software version (we only support version 10.2 or later versions)

Now we are ready to Install the LIPI

Refer to /wiki/spaces/MCSH/pages/1753120797

Putting in your API key:

a. Go to Map Editor and navigate to the Indoor Positioning menu. (If this menu is not visible to you, please send a mail to support@mazemap.com and ask for access.)

...

b. Click the LIPI Configuration

...

c. Expand the LIPI configuration and click on “Generate”. You can copy this key and paste it on your SSH

...

LIPI + CMX Architecture

Image Added