README.md 15.1 KB
Newer Older
1
<!-- KG6WXC MeshMap README.md file -->
2
<!-- May 2018 -->
Eric - kg6wxc's avatar
Eric - kg6wxc committed
3
4
<!-- <img src="https://mapping.kg6wxc.net/meshmap/images/MESHMAP_LOGO.svg" style="float:left; vertical-align: middle;"/> -->
<img src="https://mapping.kg6wxc.net/meshmap/images/MeshBanner-TEST.png" width="600" style="float:left; vertical-align: middle;"/>
5
6
<h1 style="float: left; vertical-align: middle;">MeshMap</h1><br/>  

Eric - kg6wxc's avatar
Eric - kg6wxc committed
7
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
Eric - kg6wxc's avatar
Eric - kg6wxc committed
8
[![HamRadio](https://img.shields.io/badge/HamRadio-Roger!-green.svg)](https://www.arednmesh.org)
Eric - kg6wxc's avatar
Eric - kg6wxc committed
9
[![MattermostChat](https://img.shields.io/badge/Chat-Mattermost-blueviolet.svg)](https://mattermost.kg6wxc.net)  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
10
Automated mapping of [AREDN](https://arednmesh.org) Networks.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
11

Eric - kg6wxc's avatar
Eric - kg6wxc committed
12
2016-2020 - Eric Satterlee / KG6WXC  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
13

Eric - kg6wxc's avatar
Eric - kg6wxc committed
14
Addtional Credit to: Mark/N2MH and Glen/K6GSE for their work on this project and to the rest of the [AREDN](https://arednmesh.org) team, without them this would not be a project.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
15

Eric - kg6wxc's avatar
Eric - kg6wxc committed
16
Licensed under GPL v3 and later.  
17
[Donations](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=6K5KQYYU34H4U&currency_code=USD&source=url) / Beer accepted! :) 
18
19
20
21
22
23
24

[Demo Map](https://mapping.kg6wxc.net/meshmap)

## Requirements
---------------
- **Apache webserver**  
(or equiv)  
25
26
- **PHP5+**  
- **mysqli PHP extension**   
27
- **mysqlnd PHP extension**  
28
- **openssl PHP extension**  
29
(you may only need mysqlnd, it should be safe to enable both for now)  
30
(One or more of these extensions may need to be enabled in php.ini)  
31
(if you do not already have mysqlnd, you might need to install it, `apt-get install php[5 or 7]-mysqlnd`)  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
32
(<em>the requirement for the mysqlnd extension will be removed in the near future</em>)  
33
- **MySQL/MariaDB**  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
34
(Other database systems are up to you)  
35
36
37
38
39
- **An AREDN Mesh node available over the local network**  
(Preferably connected to an AREDN network...)  
- **Map Tiles**  
(Either in a static directory or available via some tile server...)  
- **RPi3 or better**  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
40
41
42
(The DB access can be pretty slow on an RPi1, you can move the DB to another system though...)  
(If your local mesh network grows to become very large, with tunnels opened to the entire planet,<br/>
you might find even an RPi3+ to become inadequate, it'll still work, it just might be slow)  
43
44
45
46
47
- **Patience**  
(Perhaps a lot!)
- **Familiarity with Linux/Apache/SQL**  
(You don't need to be a pro, but this should not be your first trip to a command line)  

48
<blockquote style="background: #d3d3d3; margin-right: 30%;">In theory, this <em>should</em> run on a Windows system as well.<br/>
49
It does not require anything specific to Linux (<em>Perhaps with the exception of the cron task</em>).<br/>
Eric - kg6wxc's avatar
Eric - kg6wxc committed
50
There is no reason that cronjob could not be adapted to run from a Windows scheduled task though.<br/>
51
52
53
54
55
56
PHP is PHP after all.</blockquote>  

### Map Tile Server info
**Without a map tile server or static tiles, Mesh users without internet access on their systems may not see any map tiles.**  
On the mesh, you *cannot* expect the client to have internet access in order to retrieve the tiles, you must provide them yourself, one way or another.  
The main map webpage will try to check for internet access and load the appropriate maps.  
mathison KJ6DZB's avatar
mathison KJ6DZB committed
57
Default internet map tile servers can be modified in your user-settings.ini file, if you want to use "local" tile servers or directories.  
58
59
60
61
62
63
64
65

It is *way* beyond the scope of this README file to help in setting up a map tile server.  
You are unfortunatly on your own there.  
It is a time consuming and computationaly expensive process, but can be done on "normal" hardware.  
It also takes *100's of GB of HD space* if you want to map the entire world, and that *does not* include the tiles themselves, that is only for the data required to **create** the map tiles.  
A good place to start for more info is: [https://switch2osm.org/serving-tiles/](https://switch2osm.org/serving-tiles/)  
If you attempt it, be patient, you *will* get it wrong more than a few times but in the end you might be surprised. :)  

66
<blockquote style="background: #66cc66; margin-right: 30%;">Tip: Another option is that some programs, Xastir in particular, will save the map tiles they use.<br/>
67
68
You *can* use those tiles as well, but they must be made to be accessible by your webserver.</blockquote>  

69
70
You *might* be able to convince KG6WXC to create local map tiles for you, if the area you want is in the USA, he does not have the available SSD space for the entire world... yet.  
If you do ask, be prepared, it literally takes KG6WXC's system about 3-4 days just to render the tiles for a smallish area and it's kind of a PITA!  
71
<blockquote style="background: #d3d3d3; margin-right: 30%">As an example, KG6WXC once made tiles for the Mesa Az. mesh group.<br/>
72
73
It was a smallish area around Phoenix Az, out to a zoom of about 8 or something.<br/>
It ended up at around 3GB of map tiles and took about 4 days of total run time to render on the server...<br/>
74
75
<em>and</em> it had to restart a few times too, due to running out of 8GB of RAM and having to tweak a few things along the way...<br/>
It actually took much longer than the 4 days of actual run time.<br/>
76
77
Building/Using a map tile server is not for the faint of heart!</blockquote>
 
78
79
80
81
82
83
84
85
86
87
88
## Initial setup for a freshly installed Raspbian 9 (Stretch) system
----------
(*Should* work for other Linuxes as well, change where needed)

- **1: Clone the projects directory from the git repository and enter it**  
`git clone https://mapping.kg6wxc.net/git/meshmap ; cd meshmap`

- **2: Import the SQL file to create the database**  
*Example*: `sudo mysql < node_map.sql`

- **3: Create a user for the database, you might have to login to the mysql server as root.**  
89
90
Here is an example of creating a mySQL user and granting access to the node_map database:  
Choose your own password!
91
92
> `sudo mysql`  
> `CREATE USER 'mesh-map'@'localhost' IDENTIFIED BY 'password';`  
93
> `GRANT ALL PRIVILEGES on node_map.* TO 'mesh-map'@'localhost';`  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
94
> `FLUSH PRIVILEGES;`
95

96
- **4: Copy scripts/user-settings.ini-default to scripts/user-settings.ini and edit the user-settings.ini file**  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
97
    * You **must** do this or the **<em>entire system</em>** will refuse to run!  
98
    * The file scripts/user-settings.ini is the most important to get right.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
99
    It is **very important** to make sure your SQL username and password are correct in scripts/user-settings.ini!!  
100
    * Also important is, if the system that this is running on cannot resolve "localnode.local.mesh" you can change that in the user-settings.ini file.  
101
102
    * Once you save to the user-settings.ini file any changes you make will not be overwritten by future updates.  
    The "-default" files *will probably* change though and you will need to update your personal files when this happens.
103
104
    * There are many other things you can change in the ini files.  
    The default center position of the map, node expiration intervals, the header messages, logo, etc.  
105
    * *Please read* the comments in the user-settings.ini file for more info about the different settings.  
106
107
108
    * There is also a "custom.inc-default" PHP file that can be used for more site specific overrides if needed.  
    Read that file for info on what it does, it can safely be ignored by most users.
<blockquote style="background: #B00000; margin-right: 45%;"><strong>The way the user editable files are distrubuted has changed!.</strong><br/></blockquote>  
109
110
111
112

- **4.5: To make sure it is all working at this point is probably a good idea.**  
You should now be able to run get-map-info.php from the scripts directory.  
I would suggest giving it a test run or two first.  
113
Node polling can take lots of time, especially on a large network. Be Patient! :)  
114
Enter the meshmap/scripts directory.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
115
Run the `get-map-info.php` script.  
116
    <blockquote style="background: #66CC66; margin-right: 35%;">Tip: if you get a "command not found" error, you may need to run it like this:<br/> `./get-map-info.php <option>` </blockquote>
Eric - kg6wxc's avatar
Eric - kg6wxc committed
117
These are options you can send to get-map-info.php:  
118
    > `--test-mode-no-sql`  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
119
    Output to console only, *do not* read/write to the database.  
120
    <blockquote style="background: #FFFF99; margin-right: 30%">This will make sure the scripts can reach your localnode and the rest of the network.  
121
122
    This will **not** update the database, you won't see anything on the map page yet, it only outputs to the terminal for testing.</blockquote>
    > `--test-mode-with-sql`  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
123
    Output to console *and* read/write to the database.  
124
125
    <blockquote style="background: #FFFF99; margin-right: 40%;">This will ensure everything is setup correctly and get some data into your database!</blockquote>
    <blockquote style="background: #66CC66; margin-right: 30%;">Tip: <em><strong>Do not</strong></em> ctrl-C out of the script while it is using the database!<br/>
Eric - kg6wxc's avatar
Eric - kg6wxc committed
126
127
	Let it finish, even if it seems hung up.<br/>
	You should recieve some error if something is <em>actually</em> wrong.<br/>
128
	Using ctrl-C to stop the script midway will cause problems in the database, <em>do not</em> do it!</blockquote>
129
<blockquote style="background: #d3d3d3; margin-right: 30%;">If the --test-mode-no-sql is successful, you can go ahead and run the script with --test-mode-with-sql or just without any options.<br/>
130
131
Run the script without options and there is no on screen output (this is for cron).</blockquote>  

132
- **5: Copy httpd-meshmap.conf-default to the apache2 "Conf Available" directory**, `/etc/apache2/conf-available`  
133
Rename the file as httpd-meshmap.conf (or whatever you want to call it really.)  
134
135
136
Once the file is copied, you need to edit it and make sure the `<Alias>` and `<Directory>` directives have the correct paths.  
After you have made sure the file is correct then run: `sudo a2enconf httpd-meshmap`  
This is will load the config into Apache and if successful, it will tell you to reload apache, do so.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
137
    <blockquote style="background: #d3d3d3; margin-right: 30%;"><em>Other linux distibutions may require you to copy this file into /etc/httpd/extra<br>and then edit /etc/httpd/httpd.conf and add the line:</em> Include extra/httpd-meshmap.conf <em>somewhere.</em></blockquote>  
138
139
140
141
142
143
144

- **6: Load up the page: http://myhostname/meshmap/index.php and you should hopefully see your data.**  
You may or may not see any map tiles, depending on if the system you are using to view the page has access to the internet or not.  
Even without map tiles, you should still see your data being mapped out.  

- **7: The cronscript.sh file is to automatically run the polling script and can be run from cron every minute.**  
(or at whatever interval you choose)  
145
Copy the cronscript.sh-default to where ever you like and rename it to just cronscript.sh (or whatever you want).  
146
147
Then, you **must** edit the cronscript.sh file and make sure the path it uses to get to the scripts directory is correct!  
After that, create a cron entry with `crontab -e`  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
148
A cron entry is as easy as this: `* * * * * /home/pi/meshmap/cronscript.sh`  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
149
    <blockquote style="background: #d3d3d3; margin-right: 30%;">You <em>can</em> safely run the script every minute in cron like this.<br>It won't actually do anything unless the intervals specified in the ini file have expired.</blockquote>  
150
151
152
153
154
  
## Updating the scripts
----------
Simply run a "git pull" from the meshmap directory and the scripts will be updated from the git repo.  
The user-settings.inc, meshmap-settings.ini, cronscript.sh, and custom.inc files will *not* be affected by updating.  
155
156
The settings in the default ini files *may* still change and have things added or removed in future versions.  
For now tho, if the default ini files change, and you still have the old ones in use, things will probably break! Be Warned!  
157
158
159
Hopefully in the future this process can be more automated.  
  
If you make changes beyond the user editable files I encourage you to perhaps push the changes upstream, please contact kg6wxc@gmail.com if you wish to do so.  
160
    <blockquote style="background: #d3d3d3; margin-right: 30%;">I am making changes all the time, it would be a good idea to run "git pull" from time to time to find any updates.</blockquote>  
161
162
163
164
165
166
167

## Notes on usage of the map pages
----------
http://(hostname)/meshmap/node_report.php will show you all the info in the DB without trying to map anything.  
This can be useful to see if all the data is there or to find nodes that have no location set. (or other issues)  
    
There is an "admin" page, which is still in the works, what is there now does work tho.  
168
169
170
Load up: http://(hostname)/meshmap/admin/admin.php in your web browser.  
The first time the admin page is loaded it will ask you to create a username and password, do so.  
This initial user will be a "super-user" and can then add/remove other users.  
171
172
I've tried to provide instructions on the admin pages themselves.  
From the admin pages you can "fix" a nodes location, which can be helpful for those users that forget the "-" in front of their longitude. :)  
173
174
You can add the "Non Mesh" Markers, fire stations, police stations, EOC's , etc from the admin pages...  
The admin pages also allow for some maintenance of the database, more feedback is encouraged on this!  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
175
  
176
You can change the way the page looks by copying webpage/css/meshmap-default.css to webpage/css/meshmap.css.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
177
178
The meshmap.css file will override the -default.css file.  
(This also applies to other *-default.css files, there are a few, please look at them if you wish to customize the layout of the map)  
179
180
181
182

## ToDo List
----------
(In no particular order)  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
183
- [x] Finally finish my admin page idea (mostly).  
184
- [x] Add new MeshMap Logo.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
185
186
187
188
189
190
- [x] User css files will override the defaults.  
- [x] Polling script checks the DB before it runs and makes changes if needed.  
- [x] Catch more nodes information now, like 3.15.1.0b04 and hopefully some other pesky ones!  
    (this will probably cause some warnings during node polling, but it is getting the info it needs)  
    (also helps clean up the database and was a nice side effect of that)  
- [x] Make the numbers for stations and links in the attribution bar a bit more accurate I hope.  
191
192
- [x] Add a "Ruler" to allow for measuring of distance and bearings.  
    (elevation plot of the line drawn via this ruler will hopefully come next)  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
193
194
195
- [x] Station PopUps now have tabs for the different sections (main, services, links).  
- [x] Search and zoom to a node now implemented.  
- [x] Import/Export the "Non-Mesh" Markers via CSV file.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
196
- [ ] Add button for "node_report.php" (List View) on the Map. (and a link to the map from node_report).  
197
198
199
- [ ] Change css file for the "?" slide-out menu.  
- [ ] Make "Parallel Threads" work again in get-map-info script, with limits on how many can be run at once.  
    (this will greatly speed up network polling)  
200
- [ ] The "Planning" Tab.  
Eric - kg6wxc's avatar
Eric - kg6wxc committed
201
202
- [ ] Make it so other networks can export their data for use on a "Mega Map" type page. :)  
- [ ] ~~Implement N2MH's "Link aging" idea(s)~~. (Temporal Databases are crazy! this may not ever happen)  
203
204
205
206
207
  
## Contributing
----------
**Contribution is encouraged!!**  
I can't think of *everything*!  
208
If you find an improvement, typo, or whatever, please,  sign up at https://gitlab.kg6wxc.net or send an email to kg6wxc@gmail.com or something!!  
209

210
This README file last updated: July 2019 (fixed some Markdowns)