UKW Tools 0.3.5 =============== This is the third release of a set of tools for generating data from elevation data. Its main use is to visualise microwave paths and mobile radio coverage. UKW Tools can make use of the freely available Globe, GTOPO30 and SRTM data that is available for free on the Internet. The SRTM data has better spatial resolution but suffers from inaccuracies whereas the Globe and GTOPO30 data is not so fine spatial resolution, but is more accurate. I strongly recommend that you install both sets of data on your system to get the best out of UKW Tools. The basis of UKW Tools is the map, this is a representation of an area and from this other functions are used. A map may be loaded from disc (a .map file) or entered by hand, or saved to disc. The program includes some example .map files as well as other example files that are needed by the program in the data directory. About Locations =============== In many places within UKW Tools you will be asked to specify a location, this may be entered in a number of formats. The format being chosen from the format chooser control usually to the right of the location entry text box. The format may be Latitude and Longitude, WW Locator, name of a Site or Town, or NGR for UK users. The format for Latitude and Longitude is best illustrated by some examples: 53.05N 1.55W 53.05 -1.55 Both of these refer to the same location, North is positive and East is positive. The angle is in degrees and is in decimal format, it will not accept minutes and seconds format. Instead of using positive and negative formats, you can add a letter to the end of the latitude and longitude values, using N and S for latitude and E and W for longitude. You can mix them and even produce bizarre entries like: -53.05S -1.55E Which are also identical to the above values. The more digits you give for the latitude and longitude the more accurate the centre of the map. The WW Locator system is capable of great accuracy if enough letters and numbers are given. UKW Tools can accept six, eight and ten character locator references, again, the more characters the more accurate the location. Typical entries look like: IO93FB JN47HI47 JO50VI23gt UKW Tools treats upper and lower case characters identically. UKW Tools can hold lists of Sites and Towns, these may be plotted on a map. It is also possible to use these names when specifying a Map, a Point or an end point for the Path Plot. The name matching is not case sensitive and the Site list is searched before the Town list, a failure to make a match will result in an error. The NGR system is used only in the UK and like the other systems can have a variable accuracy depending on how many digits are entered. UKW Tools can handle two, four, six, eight and ten character NGRs. They will typically look like: SK SK35 SK3051 SK306516 SK30615166 The above comments about location references also apply to other parts of UKW Tools where locations also need to be entered. For a map, typically less accuracy is required than for points, but the rules are the same. Creating, Opening and Saving a Map ================================== To create a new map you should use the New Map option on the File menu. This will create a dialogue box which asks for a location and its format (see the above section), a pixel resolution and whether to display towns and sites. The resolution needed, depends on both the quality of data available and also on how much of the earth you need to see. With Globe v1.0, Globe v2.0 and GTOPO30 data which has one elevation point per 900m, any map with a pixel resolution below 1000m is not really useful, with SRTM which has one elevation point every 90m then a map with a pixel resolution below 90m is not that useful. UKW Tools gives the option to go below these resolutions, since it allows for easier viewing especially when dealing with a map with many towns or sites being shown. For each pixel resolution the map will show the following area: Resolution Map Size 30m 22.5km x 16.5km 60m 45.0km x 33.0km 90m 67.5km x 49.5km 125m 93.8km x 68.8km 250m 188km x 138km 500m 375km x 275km 1km 750km x 550km 2km 1500km x 1100km 4km 3000km x 2200km For many purposes the 250m resolution is probably the highest that is useful, however higher values produce very pretty pictures of whole countries (at least in Europe), so they have their uses. The display of towns depends on whether a towns.dat file is available, and sites on a sites.dat is available. An example of each file is included in the data directory. These, or new files, should be copied to the UKW Tools data directory, this is settable within the preferences section (see below), and under Linux this is typically /usr/share/ukwtools. The towns.dat and sites.dat files must be created manually, and the format, which is the same for both files, is shown by some examples: [Cromford] lat=53.105556 lon=-1.560278 [Pfaffhausen] loc=JN47HI47 [Wirksworth] ngr=SK305516 The rules for the location details are almost identical to those stated above, except that for setting latitude and longitude two entries and needed, see the Cromford entry above, and only digits may be used, no letters. Finally the format of the map may be changed. The choice is between a pseudo 3D representation or a simpler display that have colours based on height. Normally the pseudo 3D representation is easier to view, but there may be occasions when the elevation representation is easier to understand. This setting along with most of the other settings may be altered in the preferences section, and the settings on an existing map may be changed dynamically via the Map Menu (see later). If all is correct then a map based on the entered data will be created with the centre of the map being the location entered. To the right of the map is an information panel which shows the centre of the map, the legend and also a scale line. Other information will also appear in this panel, see later. Opening an already existing map is simple. Choose Open Map on the File menu and find the file holding the map details that you require. Map files have the file extension of .map (or .MAP) and selecting OK on the file selection dialogue with a chosen map file will cause a map to appear in the same way as for entering a map manually. A map may be saved, this may be done using the Save Map or Save Map As options on the File menu. If you have made a change to a map which has been loaded from an existing map file, then it is possible to overwrite that map file with the new map details by selecting the Save Map option. If you want to save it with a new file name then select Save Map As instead and you will be given the option of entering a new name for the file. If the map has been entered manually then selecting either Save Map or Save Map As will have the same effect, and you will have to enter a file name to save the new map under. Using the Map ============= Now that a map is being displayed, you can do things with it. The simplest is simply to move the mouse around the map, in the information panel you will see an entry which displays the current location of the mouse pointer in all of the valid systems for that location. It will also show the height of the point above sea level in metres. If you have done a Coverage Plot (see later) then you will also see information about the signal strengths that are being received from each Point that is displayed. If you are doing a Path Plot (see later) you will see a bearing and distance displayed instead. If you are using Globe v1.0, Globe v2.0 or GTOPO30 data or SRTM plus Globe v1.0, Globe v2.0 or GTOPO30 data then the sea itself will appear blue and no level will be displayed. For internal calculations this level is taken to be zero metres above sea level, although the information in the right hand panel will say "No Data" to emphasize the fact that a true height measurement is not available. To make the program useful, you need to be able to enter points that have names and can be used as the basis for further functions. These locations are known as Points and they may be entered in one of two ways, either manually or by selecting an already existing point file, named .qth (or .QTH) file. The first way is by clicking the left mouse button on the required place on the map, or by moving the mouse to the desired place and clicking the right mouse button and selecting New Location from the pop-up Map Menu. These both lead to a dialogue box where the name of the point can be entered, modify the position as well as the format of that position, and enter a height AGL in metres. This height can be something as simple as the height of a mast, or it may be the hight of the roof of a car or even the height of someone's head for a handheld radio. Optionally a height ASL in metres can be entered, this allows for the overriding of the lookup ASL height done within the program in cases where the exact height is known accurately. Leaving this height blank will cause the program to look up the height itself. When all of these have been entered then OK can be pressed and the point will be shown on the map. An existing point can be loaded from disc by clicking the right mouse button and choosing Open Point on the Map Menu. This will bring up a file selector dialogue and a suitable file may be loaded. A point may be saved by taking the mouse close to the point and clicking the right mouse button and getting the Point Menu. This allows the point to be saved under its existing file name (Save Point option), if it has one, or under a new file name, using the Save Point As option. More then one point may be displayed on the map at once. The current value is ten, but this is easily changed if needed. A point is shown as a square on the map, with its name below it. It is possible to remove a single point or all of the points from the map, but not to permanently delete it/them, by moving the mouse to the required point, pressing the right mouse button and selecting Remove Point from the Point Menu. Removing all points is done via the Map Menu and choosing Remove all Points. The Map Menu and the Point Menu =============================== Once a point (or two) have been entered onto the map, then it is now possible to do more. The keys are the two menus that I have described above. These both pop-up when the right hand mouse button is pressed, and the choice of which menu is displayed is made depending on whether the mouse if positioned near to a point or not. If it is not then the Map Menu is shown, if it is then the Point Menu is displayed. The Map Menu has the following entries: New Point... Open Point Remove all Points Coverage plot... Towns -> on Towns -> off Sites -> on Sites -> off Resolution -> 30m Resolution -> 60m Resolution -> 90m Resolution -> 125m Resolution -> 250m Resolution -> 500m Resolution -> 1km Resolution -> 2km Resolution -> 4km Map Type -> Pseudo 3D 1 Map Type -> Pseudo 3D 2 Map Type -> Elevation Re-Centre New Point and Open Point have already been covered above. Remove all Points allows for the removal of all of the current displayed points on the map, a warning message will be displayed if no points are currently being displayed. Coverage Plot is covered in its own section below, Towns on and Towns off allows for the switching on and off of the towns on the map, it displays the current status of the towns. The Sites on and Sites off does the same for the sites and operates in exactly the same way. Resolution allows the existing map to be changed to have a different pixel resolution, any displayed points will be lost as will any current coverage plots on the map. The Map Type allow switching between the two Pseudo 3D representations, Pseudo 3D 1 that was introduced with version 0.3.0, Pseudo 3D 2 which is experimental and introduced with 0.3.3, or the previous elevation display in previous versions. It is easier to see the tops of hills or mountians with the Elevation option, but it doesn't look so good for general work. Pseudo 3D 1 is good for general purpose work, but Pseudo 3D 2 is better at showing height changes, but is not so easy to look at for long periods. In all of these cases the map file will not be changed to reflect these changes unless the Save Map (or Save Map As) option is selected from the File menu. Re-Centre allows a map to be moved. After selecting this option, UKW Tools waits for you to move the mouse to the new centre and to press the left mouse button. The map will then re-display with the same pixel resolution and towns, sites and points as before, but without the coverage plots. Again, these settings will not be automatically saved to the map file unless explicitely told to do so. The Point Menu holds functions that are specific to a given Point on the map. These options are: Save Point Save Point As... Remove Point 3D Map Horizon Start Path Plot Coverage -> on Coverage -> off Properties Save Point, Save Point As, and Remove Point have all been covered above. 3D Map and Horizon and described below in detail. Start Path Plot allows for the selection of the start of a path plot, the start may only be an existing point on the map, but the end point has no such restriction. If Start Path Plot has been selected then the mouse should be moved to the desired end point, during this time the bearing and distance from the selected Point to the mouse location will be displayed in the right hand panel. When the desired location has been found, pressing the left mouse button will pop up a dialogue box, further details are below. If the end of the plot is close to another Point then that point, along with its height, will be taken and used to fill in the information in the dialogue box. If you wish to perform a path plot close to a displayed Point then you may have to remove that Point so that it is not used as the end point. Coverage on and Coverage off allow a point to take part (or not) in a coverage plot. Although there may be up to ten points on a map, a maximum of two may be used in a coverage plot. By default all newly entered points, either entered manually or read from a file, are selected for taking part in a coverage plot. If too many points are selected then an error message will be shown once a coverage plot is started. Full details of a coverage plot is given below. Selecting Properties will bring up a dialogue box that displays all of the information about the selected point held within the system. This includes its name, file name if any, its position in different formats, its mast height, its height above sea level and whether it will be used in a coverage plot. A typical properties dialogue box is: Point Name: Alport Heights File Name: /home/jsn/ukwtools-0.3.0/data/Alport.qth Latitude/Longitude: 53.06028N 1.54343W Locator: IO93FB44sl NGR: SK30605160 OS 1" Map: 119 - Buxton, Matlock and Dove Dale Height: 302m ASL Mast: 32m AGL Coverage Plot: Yes The NGR information is only valid within the UK and will not be displayed for points outside of that area. All you can do with this dialogue box is to tell it to go away. Coverage Plot ============= This function is mostly of use for determining mobile radio coverage, although it can be used in a general way for determining the quality of a location. Many of the parameters for the coverage plot may have default values set within the Coverage Preferences dialogue box under the Edit menu, see below. The routines used are known as the Irregular Terrain Model (ITM) and is based on the work of Longley and Rice in the late 1960s. It was the model of choice for the FCC until a few years ago. The coverage plot displays the area where the received signals from the start point will be received with a signal higher than a given threshold. In order to do this a number of parameters need to be entered. These require some understanding of radio technology, in particular the concept of the Decibel (dB) is extremely important. The parameters that you need are: 1. Frequency in MHz, the limits are 20 MHz and 20000 MHz. Outside of this range other propagation effects become dominant and these are not modelled correctly. 2. Polarisation which may be either Horizontal or Vertical. Many radio systems use vetical polarisation as this is the easiest to generate for mobile radios for example. Wireless LAN technology tends to use vertical polarisation also. 3. TX Power (dBm) is the power of the transmitter in dB relative to a milli-Watt. Some examples powers are: 1 mW 0 dBm 10 mW 10 dBm 100 mW 20 dBm 500 mW 27 dBm 1 W 30 dBm 2 W 33 dBm 10 W 40 dBm 4. TX Antenna Gain (dBi) is the gain of the transmitting antenna relative to an Isotropic radiator. A (theoretical) Isotropic antenna has a gain of 2.16 dB relative to a half-wave dipole. Some typical gains for small antennas are: Half-Wave Dipole 2.16 dBi Quarter Wave vertical 2.16 dBi 5/8 Lambda vertical 5.16 dBi 5. Min. RX Signal (dBm) is the minimum signal strength at the receiver that is considered acceptable. This figure is calculated from a combination of noise figure/sensitivity, bandwidth, and mode. A set of guide figures is: Mobile radio (commercial) -107 dBm -113 dBm Mobile radio (amateur) -113 dBm -120 dBm 802.11b Wireless LAN -80 dBm -83 dBm 802.11g Wireless LAN -70 dBm -73 dBm The first figure is the minimum signal that should be used if you want to model completely solid reception, typically no noise or drop-outs. A signal between the two figures will exhibit varying amounts of noise and/or drop-outs. A signal weaker than the right hand number is regarded as being too weak to be useful. If anyone can provide more values then please contact me. 6. RX Antenna Gain (dBi) is the receiver antenna gain relative to an Isotropic antenna. The same comments as in section 4 above apply. 7. Height (m AGL) is the height of the receiving antennas above the ground in metres. 8. Ground gives a choice of the different types of land that is to be found in the area being modelled. The choices are: Salt Water Good Ground Fresh Water Marshy Land Farmland, Foreset Average Ground Mountain, Sand City Poor Ground 9. Confidence (%age) is an indication to the modelling routines about the confidence that is expected in the figures returned. The values are between 1% and 99%. Figures I have seen indicate that a figure of 50% is suitable for modelling mobile radio coverage and 97% should be used for modelling digital television coverage. The higher the value, the more pessimistic are the routines and the higher the path loss, therefore for a link that has to operate at all times in all weathers then a value of 99% should be used. 10. The setting of the climate may also be given. The values available are: Equatorial Continental Sub-Tropical Maritime Tropical Desert Continental Temperate Maritime Temperate over Land Maritime Temperate over Sea For the UK, a value of Maritime Temperate over Land is suitable, whereas for mainland Europe and the continental USA a value of Continental Temperate is more reasonable. UKW Tools cannot model the effects of tropospheric ducts or other anomalous propagation conditions. However the ITM routines can model non line-of-sight paths which may include one or more obstructions and model scattering, knife-edge refraction and even tropospheric scattering. The price to pay for this is the speed of the calculations, it is slow. If only one point is selected for the coverage plot then its coverage will appear as green. If there are two points then the first one will appear as green again, the second one as yellow and any overlapping coverage will appear as blue. These colours can be seen in the information panel to the right of the map. Once there is at least one point with a Coverage Plot then the signal strength over the minimum value set (in dBm) is displayed in the right hand panel. A positive value here indicates a signal above the threshold, a negative value indicates a signal below the threshold. If the model cannot generate a reasonable value, or if there is no point plotted then "No Data" is displayed by the side of the Point number. 3D Map ====== This displays a pseudo three dimensional view of the area centred on the selected point. The value for the size of the 3D Map is taken from the 3D Map section of the Edit menu. There is a pop-up menu which is accessed by pressing the right hand mouse button. Its commands are: Angle - Increase the viewing angle by ten degrees Angle + Decrease the viewing angle by ten degrees Height - Stretch the height of the terrain by 20% height + Depress the height of the terrain by 20% Map Size Change the map size Map Type 1 Map Type 2 Palette + Goto the next colour palette Palette - Goto the previous colour palette Each one of these has a keyboard equivalent, these are: Angle - a angle + A Height - h Height + H Map Type 1 1 Map Type 2 2 Palette - p Palette + P The Map Size allows the map to be changed to a square of the following sizes: 5km 10km 20km 30km 50km 100km 200km 300km These are also accessible from the keyboard using the + and - keys to cycle through the values. Horizon ======= This display a view of the radio horizon as seen from the selected point. Before entering the horizon display, a dialogue box is displayed which allows for the setting of a number of parameters needed for the creation of the image, many of these are taken from defaults which are set under the Horizon section of the Edit menu. The entries that need to be checked and maybe changed are: Start and end bearing of the horizon view, the maximum and minimum angles for the obstructions, the maximum distance to look for obstructions and the K value to apply to the curvature of the earth. The K Values are: 1.00 1.15 1.33 1.50 Once OK is pressed the horizon view will be displayed. Horizon view has no pop-up menu or any other values that can be changed. Path Plot ========= This displays a path plot between two points. The dialogue box that appears once the start and end points have been selected on the map allow for the finer setting of the end point of the path plot, as well as the setting of the radio parameters for the ITM. The location of the end point is filled in within the dialogue box and may be altered as well as the format of the location entry changed. The rest of the dialogue box has the same entries as for the coverage plot on the main map. See the Coverage Plot section above for the meanings of the various entries. Once OK has been pressed then the path plot is displayed in a dialogue box. The land is displayed as a solid black line, the masts (if visible) are shown in green, the line of the radio signal is shown as a dashed red line. Moving the mouse shows a value for the location below the mouse and the height of where the mouse points, in addition a dashed black line is drawn from the start and end points to the mouse position. This is particularly useful when viewing an obstructed path as it is then possible to place the mouse on the obstruction and be able to read off its location. The start, end and mouse locations are displayed in every valid format, as well as displaying any up/down tilt and heights above sea level. If the path is line-of-sight then the first Fresnel zone is displayed as long dashed grey lines above and below the direct path. Any obstruction that impinges on this area will affect the signal, although most references say that such an obstruction has to block around a half of the first Fresnel zone before the affects become serious. At the top of the dialogue box are two lines that give details of the path from the points of view of signals and the estimated received strengths. An example could be: Path loss at 2400 MHz is 117.2 dB, Line of Sight EIRP is 20 dBm, received signal is -82 dBm, signal margin is +1 dB This is from modelling a 3.36 km path with wireless LAN equipment under ETSI regulations. The figures of note here are the path loss of 117.2 dB, it is line-of-sight, which is obvious from the plotted terrain. The line below is arguably of more interest, the EIRP is given, this is important as many licences are based on a maximum value of EIRP. The received signal is given and finally the margin, a positive value indicates that the signal is stronger than the minimum value given in the previous dialogue box. A negative value indicates a signal below this threshold. A path may also be labelled as Single Horizon or Double Horizon with the qualifier of have either Diffraction Dominant or Troposcatter Dominant. Any case where the path is not line of sight is going to incur large amounts of additional losses. Setting Preferences =================== Many of the values used within UKW Tools are set by preferences set within the Edit menu. The values set here can often be overridden later on in UKW Tools, however the values entered here are saved and re-read next time UKW Tools starts. The entries of the Edit menu are: 3D Map Coverage Horizon Map Paths Under 3D Map, the size of the 3D Map may be set to any one of: 5km 10km 20km 30km 50km 100km 200km 300km These may be overridden within the 3D Map dialogue box pop-up menu. Under Coverage you can set all of the values required for the coverage plot and the path plot (see above). Under Horizon it is possible to set defaults for use only within the horizon view part of UKW Tools. These are the maximum distance for calculating the horizon, more local obstructions permitting, and the minimum and maximum angles of the elevation to display. All of these values can be overridden in the dialogue box that appears before displaying the horizon view. Under Map are the settings for the default location format, which is one of: Latitude/Longitude Locator NGR (UK only) The default pixel resolution, one of: 30m 60m 90m 125m 250m 500m 1km 2km 4km And whether to display towns and sites on a map, as well as the default map type. The size of the text on the map may also be set, the default is 6 point, but that may be difficult to see on small screens. All of these values bar the text size may be overridden in various pop-up menus, dialogue boxes etc. However they are very important defaults. Under Paths you can set the file paths to access various pieces of data needed for UKW Tools. You can set the paths to point to the SRTM data, the Globe data, the GTOPO30 data, the town/sites data, and the Map/QTH data. For each of these a browse button is provided so that the full path names do not need to be entered. You can also select which types of data you want to use, one of: SRTM Only Globe v1.0 Only Globe v2.0 Only GTOPO30 Only SRTM and Globe v1.0 SRTM and Globe v2.0 SRTM and GTOPO30 The defaults under Linux are: SRTM File Path /usr/share/ukwtools/srtm Globe File Path /usr/share/ukwtools/globe GTOPO30 File Path /usr/share/ukwtools/gtopo30 Data File Path /usr/share/ukwtools Map/QTH File Path /usr/share/ukwtools DTEM Choice SRTM and GTOPO30 Unlike the other preferences, any change in these values does not take effect until the next time that UKW Tools is run. Note ==== A note for users who have set up their systems to use a comma as a decimal delimiter, you will have to edit one of the data files from the map data. Initially I suggest that you try UKW Tools as it is, if you find that UKW Tools does not cause an explicit error but shows no data on the screen then I suggest you edit the *.HDR file and change the decimal points to decimal commas. This has bitten at least one user and took some time to track the problem down. This does not affect people who are using Globe (v1.0 or v2.0) or SRTM data files which do not use decimal points or commas.