CloudRF.

com

Keyhole Radio user guide

1 Introduction 1.1 System overview 1.2 Concept of operations 1.3 Accounts and login 2 Operation 2.1 User interface 2.2 Calculate options 2.3 Transmitter options 2.4 Antenna options 2.5 Receiver options 2.6 Environment options 2.7 Layer options 2.8 Path Profile Analysis

3 Data 3.1 Terrain data 3.2 Radio templates 3.3 Antenna templates 3.4 Ground clutter 3.5 User archive 4 Miscellaneous 4.1 Linux compatibility 4.2 Repeater chaining 4.3 Exporting results 4.4 Performance tips

5 Examples 5.1 Push to talk VHF radio 5.2 Mobile phone mast 6 Technical support 6.1 Trouble shooting 6.2 Frequently asked questions [email protected]

1 Introduction
1.1 System overview Keyhole Radio is a unique and powerful radio planning plugin for Google earth . The software is server based meaning end users only need to open a Keyhole Markup Language (KML) overlay in Google earth to use it. It's ideal for organisations already using Google earth as it can be deployed effortlessly to users as a URL and the KML output is visualised along with existing data layers as a common operating picture (COP). The systems terrain data, radio templates, antenna patterns and ground clutter are all managed server side so the client only needs Google earth and a network connection. A user account is required to use the service. 1.2 Concept of operations The software acts as a plugin to Google earth. To open it, either launch the KML file from cloudrf.com or add a network link within Google earth with the url https://cloudrf.com/krs3. Once opened, you will be prompted for a password. After that you will receive several layers providing different functionality or reference data. To perform a new calculation, click the orange icon in the middle of the map screen to open up a pop-up form within Google earth or an external web browser, then enter system and environmental parameters and finally click a button to initiate calculation of the result. The variables are all passed to a server running propagation software supported by terrain, antenna and clutter datasets. The server produces the overlays and then displays a KMZ file link which needs to be clicked to be viewed. The KMZ can also be opened in compatible GIS applications which properly support the KML 2.2 standard.

Page 1 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com 1.3 Accounts and login Authentication is required to access the software. This ensures only trusted people have access to the service and ensures a higher quality of service for all. It also allows for simple monitoring and segregation of data on the server. When the layer is opened for the first time, an authentication dialogue will appear prompting the user to enter a username and password. This account must exist on the server and be defined by a system administrator within the user table. If the link is opened with http:// then a non-secure warning will be appended to the dialogue, otherwise for https:// links, the warning is suppressed and the login is protected with SSL encryption. Note: Google earth Linux does not support SSL. See Miscellaneous.

2 Operation
2.1 User Interface Once logged in, the layer will render several different features; a banner in the top left corner showing session information, a layer of green rectangles over the earth showing terrain coverage (each tile is 1x1 degree) available and an orange button in the centre of the screen. The orange button appears after the view has changed and settled and will only appear once the view has focused and zoomed into a country as opposed to a continent. To perform a calculation, click the orange button.

Page 2 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

The pop-up calculation form contains a tabbed input form with a wide range of options of varying importance. New users will be able to generate approximate calculations using just the first two tabs (Frequency/Power/Height) but for an accurate prediction, users should be adjusting settings on all six tabs to define the antenna parameters, environment variables and receiver type and threshold. The form can also be opened outside of Google earth using the open in web browser hyperlink. This can be beneficial to users with multiple monitors who can keep their Google earth view clear of visual obstructions. The hyperlink opened is unique to the logged in user and expires after a time. Bookmarking or sharing the link is not advised. Initially, the location used will be the centre of the screen. This can be adjusted within the second tab. 2.2 Calculate options The first tab contains the most basic values and the calculate button which is used to start the calculation. Template The template box will display a list of saved radio templates after 3 characters eg. VHF have been entered into it. The templates can be selected with a click and will automatically populate the relevant fields within the form with saved values. To add a template click the Add hyperlink to the right. For more on templates, see the data section. Page 3 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

Frequency Enter the channel frequency of the radio system in megahertz (MHz). Acceptable values are 20 to 20,000MHz. ERP Enter the total effective radiated power (ERP) of the radio system in Watts. Novice users should just enter their radios wattage as per its specification eg. 5W. Advanced users can enter transmitter power (W) and antenna gain (dBi) to automatically calculate the ERP on the antenna tab (#3). Maximum value is 2MW (2,000,000W). Radius Enter the maximum distance in either kilometres or miles for the coverage plot. This should be no more than the range of the most distant station. To change distance units, click metres or feet within the second transmitter tab. The maximum value possible is determined by the server and is typically 200km. Calculate The calculate action button executes the calculation. Whilst running, it will be greyed out and cannot be clicked until the calculation completes. In the event of a calculation result failing to display (>60 seconds delay) the form must be reloaded to reset the button. Description The filename description field allows for up to 25 characters to describe a calculation, for example Fire station. This name is visible in both the archive and the KML layer within Google earth. If left as Description it will result in the default filename of date, time and frequency.

2.3 Transmitter options The second tab contains geographic information including the emitter location, height above ground level and distance units. Antenna location Enter the location of the emitter in either Decimal degrees, Degrees-minutes-seconds or NATO Military Grid Reference System (MGRS). Entering a value within one row will automatically result in a conversion to the others. By default this is the centre of the screen. Antenna height Enter the height of the antenna above the ground. The metres or feet toggle next to it will also change distance units for all other measurements within the form including radius and receiver height(s).

Page 4 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com 2.4 Antenna options

The third tab contains advanced settings related to antenna radiation patterns. It allows a choice between pre-made 3D templates or a custom 3D pattern based upon user supplied values. For both methods, there will be two adjacent images shown which depict the horizontal (birds eye view) and vertical (side on) radiation patterns. Most users should find a template to suit their needs and will only need to rotate the antenna by defining the direction (degrees from north) field. Templates Templates are stored in a database in .ant v3 format (360 rows of horizontal values, 360 rows of vertical values) compatible with other popular planning applications. A template is selected by choosing it from the drop-down menu. New templates can be uploaded in .ant or .pat formats via the Add link. To compare all patterns in detail click the Add link to open the antenna dashboard. All antenna patterns are referenced to 0dB (100% radiation) so a round green pattern with 0dB all round would be radiating at 100% power in all directions. Custom The custom option allows users to create a pattern on the fly by defining key fields (direction, downtilt, horizontal beamwidth, vertical beamwidth, gain, front-to-back ratio). As values are changed within these fields, the pattern will automatically update. Tip: Novice push-to-talk (PTT) users should select a Dipole.ant (omni-directional monopole) pattern. Polarisation Antenna polarisation/polarization describes the physical orientation of the antenna. Most broadcast systems are vertical, whilst some data systems are horizontal to reduce (vertical) interference. Default is vertical.

Page 5 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com Direction The horizontal angle (azimuth) the antenna is pointing referenced to grid north. Values of 0360 are allowed. Not to be confused with beamwidth. Down tilt The downtilt is the vertical angle the antenna is pointing relative to the horizon. Acceptable values are -10 to (+)90 degrees where angles above the horizon (pointing up) are negative and angles toward the earth (pointing down) are positive. If an antenna was parallel to the ground it would be 0 degrees. For example, a directional antenna on top of a tall hill pointing down into a valley would have a positive downtilt. A similar antenna down in the valley would have a negative downtilt as it would be looking up the hill. Default is zero (no tilt). Horizontal Beamwidth This describes the angle in degrees between the two half power (-3dB) points of a directional antenna in the horizontal plane. For example, a directional one third panel on a GSM cell tower would have a beamwidth of 120 degrees. This setting can only be applied in custom pattern mode. Vertical Beamwidth This describes the angle in degrees between the two half power (-3dB) points of a directional antenna in the vertical plane. For example, the previously mentioned 120 degree (horizontal beamwidth) GSM panel may have a smaller vertical beamwidth of only 30 or 45 degrees, otherwise it will be wasting energy radiating the sky above it. This setting can only be applied in custom pattern mode. RF Input Power Transmission RF power in watts is the amount of power supplied by a radio and is normally smaller than the total effective radiated power (ERP) of a directional antenna system. It is used along with gain to calculate the total effective radiated power (ERP) of the system. Max Gain The directional gain of an antenna measured in dBi. This is a numerical value between 0 and 50. For 1:1 gain (no additional power) then a default figure of 2.15dBi should be used. A high gain antenna would be greater than 10dBi. Adjusting this will result in an automatic adjustment to the ERP value on both the antenna tab and the initial calculate tab. Front to back ratio This ratio measured in dB relates to the difference in power between the front and the back of the antenna. A value of 2 would mean the antenna was almost as powerful to the rear as to the front whereas 40 would mean nearly no power was radiated to the rear. This is automatically set to twice the gain so a 7.5dBi antenna would have a 15dB FBR. Maximum is 70dB. ERP Effective Radiated Power (ERP) is the total RF output of a system and is automatically calculated using the following formula:

ERP = Transmitter Power * Feedline Loss * Antenna Gain This value, once changed is automatically set on the first Calculate tab as well.
Page 6 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com 2.5 Receiver options The fourth tab contains advanced settings relating to the receiver(s) settings. An incorrect value here can result in significantly unrealistic results. Receiver height The height above ground level of the receiver(s). Distance units are defined on tab two. For a man holding a handheld radio or phone, set this to 2 metres. Units of measurement The output units determine how to represent the propagation. Selecting dB (decibels) will ignore the Power output (ERP) and depict the path loss caused by the terrain. Handy for identifying high loss blackspots in the terrain. Selecting dBm (decibel milliwatt) will factor in all variables and depict the radio coverage. This should be used as standard or when uncertain. Selecting dBuV/m (Decibel microvolts per metre) will show the electrical field strength present in the ground and is best used for scientific surveys relating to RF radiation levels. Receiver sensitivity The coloured key and selected value changes according to the measurement units selected above it. For all three units, a strong signal is to the left (yellow) and a weak signal is to the right (purple). An optimistic result can be achieved by setting the slider to -110dBm whereas -50dBm would provide a more cynical result and can provide extra realism in suburban environments where ground clutter is not available to simulate concrete screening and absorption. If you do not know your receiver sensitivity then -90dBm is a good average.

2.6 Environment options The fifth tab lists advanced options for defining man made obstacles (clutter) and ground conductivity. The features here will help advanced users achieve the most realistic coverage plot for an area, especially in suburban or extreme climatic environments. Random clutter Buildings can be rapidly simulated using the slider, up to 50 metres (150 ft) high. This will increase the ground height all around the site to simulate a layer of buildings above ground level. Database clutter A much more precise simulation of man-made buildings can be done by uploading an overlay of Page 7 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com points to mark building locations via the Upload KML hyperlink. This overlay should be a KML containing either placemarks, polygon corners, line points with heights in metres defined in the point properties. A quick way to define a row of two storey buildings is to use the Google earth line feature and click once per building then set the lines height to 6 metres in Google earth. Save off the line to a .kml file and upload it. A single click will create a 90mx90m building. To define a larger building, click each corner. Ground conductivity The conductivity slider allows you to compensate for different environments using a dielectric value which describes electrical conductivity through the ground. A city has very poor conductivity whilst a wet marsh has very high conductivity. This is relevant for radio systems which operate at ground level such as hand held radio. Climate The climate slider allows you to compensate for different environments using a climate code which affects propagation through space. This is relevant for radio systems which operate high up such as over the horizon microwave links. 2.7 Layer options The sixth tabs options do not affect actual propagation results with the slight exception of resolution which changes the granularity of the output. They determine formatting of results after calculation. Resolution This option relates to the pixels per degree of output files. A high resolution employs 1200 pixels for each degree on the earth which at the equator is about 90 metres. This figure reduces towards northern latitudes. A medium resolution is 600 pixels so twice the distance and low is half again (300 pixels). Calculation time is affected significantly by the resolution. Transparency The transparency/opacity slider applies to the Google earth ground overlay. This value can also be manipulated post calculation manually within the layers properties. Colour schema The colour of the output file can be set here. For single colours like Reds a range of dark and light reds will be used to denote strong and weak signals. A key is supplied with each layer for reference. Greyscale terrain background Enabling this will draw the terrain background for the overlay which can be helpful when sharing the layer with other users or viewing it on systems with limited mapping. This feature greatly increases resultant filesize.

Page 8 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

2.8 Path Profile Analysis The Path Profile Analysis (PPA) feature allows a point to point (P2P) study from the transmitter (Tx) which generates a 2D profile graph and text report highlighting obstructions. To use the PPA feature select a radio coverage layer and then focus the viewer on to a point within the coverage area where you would like to have a receiver (Rx). Expand the layers components within the left hand layer tree to reveal the Path Profile Analysis network link, select it and press Ctrl-R to run a PPA. (Alternatively, right click the layer then select refresh) After a brief delay, a signal strength icon will appear on the map centred on the centre of view with a value representing the signal strength. Click this icon to view the report and 2D graph with Fresnel zones.

3 Data
3.1 Terrain data The system uses public Shuttle Radar Topography Mission (SRTM) version 2 data sourced from the NASA 2000 mission which is a modified dataset improved by the National Geospatial Intelligence Agency (NGIA). The modifications removed erroneous spikes although the data still contains a small number of voids in mountainous terrain caused by radar shadow. The public data is accurate to 90 metres / 270 feet and equates to Digital Terrain Data (DTED) level 1 for Government users. The NASA data extends to 60 degrees latitude in both

Page 9 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com poles with extra polar data courtesy of Cartographer Jonathan De Ferranti BA (http://viewfinderpanoramas.org) who has created the data. The data only depicts the earths surface and does not generally include man-made structures however large elongated concrete features (present in the year 2000) have been included. Tall sky scrapers were smoothed out of the data as part of the version 2 data scrub. The picture below depicts the presence of man-made obstacles within the SRTM data as radio waves are visibly affected by concrete pontoons in Marseille harbour.

Man made obstacles created after the year 2000 are not factored in as this picture shows. The Dubai Palm Jumeirah development was started in 2001, much to the dismay of NASA scientists.

Page 10 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

3.2 Radio templates Common settings for radio systems can be saved into a database and recovered quickly later by typing either the name or frequency into the templates box. To save a template, click the Add link next to the template search box to launch the save dialog. Users must supply a description to name their template (Tip: Keep it unique so you can find it later) and then click the save disk icon to write it to the database. Any incorrect names or values will generate an error message at the bottom on the calculate tab so keep an eye on this. Users own templates will be highlighted light blue when searching. By default, templates are visible by all users.

3.3 Antenna templates The system allows the definition of antenna radiation patterns in both the horizontal (azimuth) and vertical (elevation) planes. A dedicated interface with examples exists for uploading these patterns. To open the antennas interface, click the Add hyperlink within the Page 11 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com antenna options tab. The file format accepted is the plaintext .ant pattern format which must contain 720 rows (360 azimuth, 360 elevation) of (negative) numbers representing antenna gain referenced to zero decibels. For an isotropic antenna (100% radiation in all directions) each row of the isotropic.ant files would read -0.0. Another popular antenna pattern format is the .pat format which has 540 rows (360 azimuth, 180 elevation). A script to convert these to .ant format can be found at ../antennas/pat2ant.php

3.4 Ground clutter As well as terrain data, users can improve accuracy by adding obstacles / clutter above ground level to simulate man made buildings, tree lines and other features not represented by the SRTM data. When an item of clutter is added at a point, it causes the ground height to be increased by the height of the obstacle.

Page 12 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

To create custom obstacles, use either the placemark, polygon or line tools within Google earth to make points on the map. Adjust the altitude option of the points to set the height of the obstacle. All heights are taken as metres so for a 100ft building, enter 30m. Once your points have been defined, save off the layer as a kml file, then upload it via the KML upload form linked from the environment (fifth) options tab. If correctly formatted, you should see each point listed as a location and height and a report declaring how many were successfully inserted into the database. Using the newly added clutter is as simple as selecting either Personal or All within the environment options tab. By default only your own (personal) clutter is enabled so you wont be inconvenienced by other users clutter which may be speculative in nature.

Page 13 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

Demonstration of user contributed clutter to define the Palm Jumeira island.

3.5 User archive Every calculation performed is saved on the server so can be recovered later on. To view your archive, click the folder name under the Data category within the layers tree. You will be prompted for your login again. Note: This protects your archive from unauthorised access but also allows you to bookmark it for reference without Google earth. Notice: The authentication prompt doesnt always work first time. Click cancel on the first (Google earth) authentication dialogue to spawn a web browser. Login to your archive with your Keyhole Radio username and password. This link can be bookmarked and accessed outside of Google earth like https:// ../krs/users/. Archive layers can be sorted, viewed/downloaded or deleted. To sort, click a column header, to view a layer in a web browser with Google maps, click the Map link column on the right, to download to your desktop or Google earth click the KMZ filename column. Tip: Use the description field on the calculate form (#1) to give recognisable names to your layers.

Page 14 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com Recovering historic settings Using the archive you can easily restore settings used in the past to perform a similar calculation again. To do this, click Launch form on the right side of the row to open a new Keyhole radio input form in a browser. Settings will be restored to exactly what was used to generate the layer.

4 Miscellaneous
4.1 Linux compatibility Keyhole radio can be used with Google earth Linux but it requires modifications to use it. The first is the initial authentication prompt which will not work in (secure) SSL mode. To change this, either right click the network link and edit the properties for the hyperlink so that it starts with http:// instead of https://. Eg. http://cloudrf.com/krs3/ or to use SSL replace /opt/google/earth/free/libcurl.so.4 with /usr/lib/i386-linux-gnu/libcurl.so.4 which has been compiled with SSL support (Tested with Google earth 7.0.x on Ubuntu 12). The next problem will be that the pop-up form tabs wont display fully either in its native balloon or the Google earth browser so must be used in an external web browser. The form will need to be reopened each time the location is changed or else the location will need to be changed manually within the second tab. Finally, the KMZ output file once clicked will spawn a new version of Google earth instead of opening in the existing instance. 4.2 Repeater chaining Often, users will have a requirement to visualise multiple emitters in a network together. Using the standard rainbow colour schema will present problems where coverage overlaps as a strong area (green) from one mast may appear weak (blue) due to an overlapping neighbour site. To eliminate this users are recommended to utilise the primary colour schemes and reduce receiver sensitivity to minimise the range of colours . Once an acceptable network picture has been generated the combined KMZ layers can all be merged into one using Google earths native layer management functions. Create a folder within the layers tree then drag the emitters into the folder, now right click and save the folder off as a single KMZ eg. mynetwork.kmz. When attempting PPA predictions in a busy network, ensure you have the right emitter selected in the network tree. The required one is the layer which has the transmitter at one Page 15 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com end of your link. Trying to create a PPA by refreshing a PPA link for a layer not even in view will result in an error. 4.3 Exporting results Layers can be shared by right clicking them and selecting either Save place as or Email to from within the layer tree. Alternatively, each layer within the users archive has a unique URL which can be shared, handy for larger overlays. These KMZ hyperlinks can also be used with Google maps to visualise them by users who may not have Google earth.

4.4 Performance tips Reduce your resolution to low to speed up calculation (Layers tab #6) Reduce your radius to speed up calculation (Calculate tab #1) Set Greyscale background to off to reduce filesize (Layers tab #6) Use a primary colour schema to reduce filesize (Layers tab #6) Reduce receiver sensitivity to reduce filesize (Receiver tab #4) Set Database clutter to none to speed up calculation (Environment tab #5)

Page 16 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com

5 Examples
5.1 Push to talk radio Frequency: 446MHz, Power: 1W, Radius: 10km, Antenna height: 2m, Polarisation: vertical, Pattern: Dipole, Azimuth: 0, Tilt: 0, Receiver height: 2m, Units of measurement: dBm, Receiver sensitivity: -85dBm, Random clutter: 4m, Database clutter: none, Ground conductivity: 12, Climate: 6, Resolution: high, Transparency: 50%, Colour schema: rainbow, Greyscale: off. 5.2 Mobile phone mast Frequency: 930MHz, Power: 10W, Radius: 30km, Antenna height: 10m, Polarisation: vertical, Pattern: Dipole, Azimuth: 0, Tilt: 0, Receiver height: 2m, Units of measurement: dBm, Receiver sensitivity: -115dBm, Random clutter: 4m, Database clutter: none, Ground conductivity: 12, Climate: 6, Resolution: medium, Transparency: 50%, Colour schema: rainbow, Greyscale: off.

6 Technical support
6.1 Trouble shooting If you encounter a problem with the software you can diagnose the cause yourself by opening the software in a different web browser as well as Google earth to eliminate either the software or the browser/Google earth as being at fault. For example, if you cannot login initially and/or are getting error prompts in Google earth then open up the same network link URL in a web browser and see if there are any giveaway signs like a server error code (403 forbidden, 404 not found etc) which wouldnt be visible in Google earth. If its working you will see the same authentication prompt in your web browser as you did in Google earth followed by some KML code. The software is server based so is vulnerable to network issues both on the users network and the internet. Network connectivity to https://cloudrf.com should be proven as part of any fault finding process. 6.2 Frequently asked questions Available at http://cloudrf.com/Keyhole_FAQs Q. I registered but didn't get sent an account A. Check your spam folder or register again with your correct email address. Q. When I launch the layer, I get asked for a username and password A. This is the same as your CloudRF account. Enter your username, not email address. Page 17 of 18 Copyright 2013 Farrant Consulting Ltd

CloudRF.com Q. I'm using Linux Google earth but it doesn't work?

A. Adjust the network URL to remove SSL so it reads: http://cloudrf.com/krs3 All calculations will need to be performed in an external web browser, otherwise all other functionality is as per windows.

Q. My hotmail.com account no longer works A. Hotmail.com / .co.uk has been blocked due to excessive spam. Register with another email.

Q. When I perform a calculation I get an '8' back from the server. What's wrong? A. Your receiver sensitivity is out of bounds.

Q. I want to view path profile analysis but when I press Ctrl-R nothing happens A. Ensure you have the PPA network link for the correct layer selected then try it or right click it and select refresh.

Q. I have overlapping layers and want to view PPA for a given point for both but can only do one/none? A. Zoom in to the receiver site then select the PPA network link for each layer you want to examine and refresh it.

Q. The orange icon isn't in the middle of my Google earth, its offset. A. The calculate icon centers itself in the middle of the screen when you are looking straight down at the ground. Adjust your view so you are not looking at the ground at an angle otherwise it will appear offset each time you change view.

Page 18 of 18 Copyright 2013 Farrant Consulting Ltd