KiwiSDR Operating Information

Updated 18 April 2024

KiwiSDR 2:
New Kiwi owners:


KiwiSDR 2:
KiwiSDR 1:
The software version is displayed on the Stats tab of the main control panel. The image below shows a version of "v1.282"

The easiest way to update is to power-up or restart when a connection to the Internet is available on the local network. The Kiwi checks for new software whenever it starts.

If it is successfully updating you will get an "update in progress" message when attempting to connect.

There is also an Update tab on the admin interface (see below) for controlling various aspects of the update process.


Beagle root password:


Did your Kiwi not have a Beagle/Linux root password set and now it's asking for one?
Recent security changes have automatically applied a password to any root or debian account passwords that were blank/unset.

The new password set is the Kiwi's serial number as shown on the admin page network tab or as written on the the Kiwi circuit board (or as written on the bottom of the enclosure with KiwiSDR 2). For some versions of KiwiSDR 1 the password might be the same as the Kiwi admin password. The debian account password might also be the default "temppwd" if the password change process failed.

Also note that with Debian 9 and later logins using the root account are no longer enabled by default. Instead, login using the debian account and "sudo su" to get a root shell.

Introduction:
For everyone:
For owners / admins:
How it works

The KiwiSDR is always accessed over a network connection using a browser running on another computer or mobile device. This can be from your local network or by anyone on the Internet if you have chosen to make your KiwiSDR publicly available. The user interface is only moderately optimized for mobile devices and there are no mobile apps yet for Android or iOS. The software does not support attaching a monitor or keyboard/mouse directly to the Kiwi BeagleBone.

Connect to the local network using an Ethernet cable between the Kiwi and your Ethernet switch, router, cable modem or firewall. An IP address for the Ethernet port is usually assigned by a DHCP server that is likely to already be running on your network. See the network configuration section for complete details.

Please consider making your Kiwi publicly available to Internet users by listing it on rx.kiwisdr.com Particularly if your Kiwi is located in an interesting or under-represented part of the world. There are options for limiting public access to a subset of the four available channels.

Just tell me how to connect to my local Kiwi

For KiwiSDR 2 try the serial number based link (replace "21xxx" with your actual serial number) For any KiwiSDR try these links if the computer running the browser is on the same local network as your Kiwi: If these don't work use one of the methods below to find the Kiwi's IP address. Then use the IP instead of "kiwisdr.local", e.g. 192.168.1.123:8073 Type this into the address bar of your browser. If you have multiple Kiwis "kiwisdr-2.local", "kiwisdr-3.local" etc. can be used.

More information about Kiwi networking.

List of third-party extensions and software packages

Here is a list of Kiwi extensions and related software packages available from third parties.
When installed the extensions will appear in the Kiwi extensions menu.

Extensions:
Software packages:
Installing the KiwiSDR and software

KiwiSDR 2: KiwiSDR 1:
Network configuration

Additional information:
The two cases of network configuration
In certain circumstances you may not have to do any network configuration at all. The Kiwi will just work out-of-the-box after you plug into the local network. There are two cases. First case, local only use:
It is likely your local network already has a DHCP server that will automatically assign an IP address to the Kiwi. This function is usually performed by your network router. The kiwisdr.local hostname resolves to this IP address via software on the Kiwi and the host computer you're connecting from (the one running your browser). But the kiwisdr.local hostname may not be recognised by all systems, particularly Windows. For a workaround to this problem, or if you need to specify the IP address manually (e.g. 192.168.1.10:8073), see below for how to find your Kiwi's IP address.

Second case, public access:
For public access you face a couple of issues.
Allowing public access on port 8073
For the public to connect, your KiwiSDR must answer on port 8073 at a fixed public IP address. Although any port number, e.g. 80, can be configured (see below). If you are on a residential network a single public IP address is sometimes shared by multiple computers, usually via Network Address Translation (NAT). You must modify the NAT configuration of your router to route connections to port 8073 of your public IP address to whatever local IP address was assigned to your Beagle (port mapping). To do this you'll need the network information provided using the methods described below. If your router supports UPnP the Kiwi can create the NAT entry automatically.

The other issue is that port mapping requires the local IP address of your KiwiSDR be unchanging over time. After all, you have to enter a fixed local IP address when the port mapping entry is made. Your KiwiSDR was likely initially assigned a local IP address with DHCP (dynamic host configuration protocol) from your router. DHCP does not guarantee that the same local IP address will be assigned each time the KiwiSDR is booted. To solve this problem most routers have another table to assign local IP addresses based on the unique MAC address associated with the Beagle. The MAC address is provided using the methods described above. You must then pick an unused local IP address that is outside the range of local IP addresses that DHCP uses yet still part of your local IP address space.

For example, our local network uses the address block 192.168.1.1 - 192.168.1.254 and is allocated as follows:

IP address fixed address?
192.168.1.1 yes router
192.168.1.2 start of DHCP allocated space
192.168.1.99 end of DHCP allocated space
192.168.1.100 yes web server
192.168.1.101 yes public KiwiSDR
192.168.1.102 yes development KiwiSDR

The port mapping and fixed IP tables are then setup in the router as follows:

NAT port mapping:
public
IP address 		port maps
to 		private
IP address		 port service
103.26.16.225 80 ----> 192.168.1.100 80 web server
103.26.16.225 8073 ----> 192.168.1.101 8073 public KiwiSDR

fixed IP assignment:
local
IP address 		Beagle MAC host
192.168.1.100 1C:BA:8C:A1:BE:EF web server
192.168.1.101 84:EB:18:E2:0E:A2 public KiwiSDR
192.168.1.102 1C:BA:8C:E3:3D:0B development KiwiSDR


Using UPnP to open the router port automatically
Beginning with release v1.65 of the Kiwi software your router can be contacted by the Kiwi using the Universal Plug-and-Play (UPnP) protocol and asked to open port 8073 automatically. Not all routers support this protocol, or have it enabled by default. This Kiwi feature is designed to save you from performing this task manually which can sometimes be difficult if you are not familiar with Network Address Translation (NAT) rules and the operation of your router.

For security reasons this feature is disabled on the Kiwi by default. To activate, go to the network tab on the admin page (e.g. kiwisdr.local:8073/admin) and set the button called Auto add NAT rule on firewall / router? to "yes". After a moment a message should say:
Automatic add of NAT rule on firewall / router: succeeded
If there is a different message in any other color the automatic add didn't work and you'll have to add an appropriate NAT rule for port 8073 (or another port you've configured) to your router manually.

Finding the Ethernet IP address of the KiwiSDR
Figuring out the IP address assigned to your KiwiSDR is the first step in manual network configuration. In most network setups a DHCP server on your router will assign this IP address to the Ethernet port on the Beagle of your KiwiSDR. The problem is figuring out what this address is. Here are some suggestions:
Use my.kiwisdr.com to connect to the Kiwi
If your Kiwi is able to contact kiwisdr.com when it starts up it will register its local IP address. Then when a browser from a computer on the same local network connects to my.kiwisdr.com it will automatically be redirected to the Kiwi. The local IP address will appear in the browser address bar. If multiple Kiwis are present on the network the browser will display a table allowing you to connect to each Kiwi individually.

Use "kiwisdr.local:8073/admin" to connect to the Kiwi admin page
The network information about your KiwiSDR is available on the "network" tab at kiwisdr.local:8073/admin So if you can connect to the Kiwi this way the Kiwi itself can tell you its IP address for use in further network configuration. If you have multiple Kiwis "kiwisdr-2.local", "kiwisdr-3.local" etc. can be used. But this method may not always work.

Most versions of Windows don't recognize the kiwisdr.local hostname. Here is a workaround. But do not use this workaround for Window 10 or later. There appears to be some sort of conflict and using kiwisdr.local will result in connections that have lots of audio overrun problems. Use one of the other methods listed here to find the IP address.

If you install Apple iTunes for Windows then the Apple Bonjour mDNS-based location discovery software gets installed. Now kiwisdr.local should be recognized. It is possible to uninstall iTunes but leave Bonjour/mDNS working with the right Windows control-panel manipulation. We understand that future versions of Windows may include mDNS by default. So try using kiwisdr.local before using the workaround.

Read the IP address from the Beagle LEDs
Beginning with version v1.174 of the software, the four LEDs on the Beagle (lower board of the two board stack) will display an encoded status message. This message includes the IP address, either assigned by DHCP or set statically. See the section: Getting the IP address (DHCP-assigned or static) from the LED pattern.

Use the free Fing network scanner app for iOS/Android at www.fing.com
There are also free third-party network scanner apps. We use one called Fing for the iPhone / iPad. After the scan, look for an entry where the Ethernet MAC address vendor has decoded to "Texas Instruments". TI is the manufacturer of the processor chip on the BeagleBone where the Ethernet controller resides.

Check your router's list of DHCP-assigned IP address
Of course your router, or other device running DHCP, knows the IP address allocated to the Kiwi. If you know how to access this device you might be able to determine the latest "new" device added to the DHCP list and hence the IP address.

Specifying the connection URL
This is the second issue to consider for the case of a Kiwi with public access. The method used to establish a public connection to your Kiwi is specified in the connect tab on the admin page. This includes specifying your own domain name, using the detected public IP address of the Kiwi or specifying your own IP address. Also the advanced techniques described below.

Configuring the dynamic DNS update client (DUC)
An issue you must consider for public access is how the outside world will contact your Kiwi. Do you already own a domain name (e.g. bob.com) and has your Internet provider assigned you a static public IP address? Great, you're all set. All you have to do is create a sub-domain, say kiwisdr.bob.com and point it to your public IP. Now your Kiwi will be reachable at kiwisdr.bob.com:8073/ assuming you're using the default port 8073.

But for many people this is not the case. They don't own a domain and their relatively inexpensive residential Internet service supplies them a dynamic IP address that changes every so often. To overcome these issues what you want is something called "dynamic DNS (DDNS)" where a company like noip.com allows you to use one of their generic domain names. And also gives you a program (dynamic update client, "DUC") to run on your local computer that tells them when your ISP has changed your dynamic IP so the generic domain name can be updated.

To simplify this process beginning with release v1.83 a DUC for noip.com has been built into the Kiwi software and can be configured on the connect tab of the admin webpage. You can use either the free DDNS noip.com service that requires a manual acknowledgement every 30 days or one of their paid plans without this restriction. Go to noip.com and create a unique hostname for one of their generic domains (e.g. kiwi1234.ddns.net) and setup an account. Then on the connect tab of the Kiwi admin page select "DUC domain" on the menu. Then enter the noip.com account information, host name and hit the "click to (re)start DUC" button. In the status field below you should see the response "DUC started successfully" or an error message if there is a problem. To start the DUC every time the Kiwi restarts change the "enable DUC at startup?" switch to "yes".

Configuring a reverse proxy
The rules for the proxy service are changing. Please see this Kiwi forum thread for details.


Instructions for existing KiwiSDR 1 users (and KiwiSDR 2 manual configurations):
Multiple proxied Kiwis behind a single Internet connection Updated
It is possible to run multiple Kiwis using the proxy behind a single Internet connection. Do this by requesting one unique user key per KiwiSDR 1 (KiwiSDR 2's have a unique proxy key built-in).

Give each Kiwi a unique host name in the proxy section of the admin page, connect tab. For KiwiSDR 2 this can either be the serial number when the Automatic configuration? switch is set to Yes. Or your own host name (if available) if the switch is set to No.

This works even if all the Kiwis are configured to use port 8073 on the local network.

Configuring an Ethernet static IP address
If you are unable if get your router to associate the Beagle Ethernet MAC to a fixed local IP then there is an alternative. It is now possible to configure the Kiwi to use a static local IP address rather than obtaining one via DHCP. You'll have to get initial access to the Kiwi using one of the methods above. But then you can go to the admin page (e.g. kiwisdr.local:8073/admin) and then the network tab and change from DHCP mode to a static IP appropriate for your local network. The Kiwi Beagle will use this IP address on the Ethernet interface when next booted.

Using a USB network connection for initial Beagle access
If your network is very limited and has no DHCP server at all you can get initial access to the Kiwi by using a USB cable between the Kiwi Beagle and another computer as the network connection (micro-USB for BeagleBone Green, mini-USB for BeagleBone Black). This is a standard feature of the Beagle and instructions are available here. Note that it requires the installation of a USB networking driver on your computer. Once logged into the Beagle using the ssh (Linux) or PuTTY (Windows), and gaining a root shell, program setup a static address for the Ethernet interface by editing the file /etc/network/interfaces on the Beagle. Change the entry for eth0 from using DHCP to using a static address. Use the entry for usb0 a guide.

But note the Kiwi software itself does not support using USB networking. This method is only for gaining initial access to the Beagle in order to change the Ethernet configuration so the Ethernet can subsequently be used.

Using a serial connection
As a last resort it is possible to connect a serial cable between the Beagle and a host computer. You'll need to purchase a USB-to-serial cable that is designed to connect to the Beagle serial port header. More information is here. Be certain to buy a cable that presents 3.3V to the Beagle and not 5V (the 5V cables are more common). You'll need to remove the Kiwi board in order to access the Beagle's serial header. Use a serial com program to login to the Beagle at 115.2k baud using the debian account and obtain a root shell. Then edit the file /etc/network/interfaces and change the configuration of the eth0 (Ethernet) interface from dhcp to static. Use the settings for usb0 at the end of the file as a guide.

Point-to-point Ethernet connection to a host computer
For step-by-step instructions on how to do this with Window 10 see this Kiwi forum post. This should works with most recent Windows versions.

Some users simply want to install an Ethernet cable directly between the Kiwi and a laptop or PC and not involve other equipment (like a router) and not involve the Internet. This might be because they are traveling or only have a wireless connection between their PC and an Internet access device that has no Ethernet ports. We now have a solution for this case.

Starting with the v1.47 release the Kiwi software uses something called avahi-autoipd which takes over when the Kiwi is unable to locate a DHCP server to get an IP address for the Ethernet port. A random-but-unique link-local IP address in the 169.254.0.0/16 range is then assigned to the Ethernet. Similar software present on all modern Macs and PCs does the same thing. Now the PC and Kiwi should be able to talk to each other. Since you don't know what IP address has been assigned to the Kiwi you instead use the name kiwisdr.local. On Windows this currently requires the Bonjour/mDNS package to be installed with the workaround described here. Macs are already setup. So now you can connect to the Kiwi by using kiwisdr.local:8073/ and kiwisdr.local:8073/admin to administrate.

It's also now possible to observe the Beagle LEDs to see what IP address was assigned.

Note that it takes
more than 60 seconds
after the Kiwi boots before it decides there is no DHCP and it should assign a link-local address. So please be patient before trying to connect from the PC.

A question remains however. If your PC only has a wireless connection to the Internet, and your new Kiwi was delivered with an installed software version prior to v1.47 (which is going to be true for quite a while) and you can only plug the Kiwi into the PC, then what can you do? The answer is to download a special version of the Kiwi software from the Internet onto your PC. Then copy it to a micro-SD card. And finally re-flash the Kiwi on-board filesystem from the SD card. Follow the instructions here.


/admin web configuration interface

Almost all configuration and administration of the KiwiSDR is done through the admin web interface at kiwisdr.local:8073/admin (adjust hostname as required). Each tab at the top of the page selects a group of related configuration parameters or status information. A restart button for the server will appear when certain parameters are changed. Use it when you have made all of your changes in all of the tabs.
Control

Restart, reboot and power off
The status tab has restart, reboot and power off buttons. Restart can be used when the server is behaving oddly. Reboot of Debian can be done if the system has been running for many days or weeks and seems to have problems that might be Linux related. It is especially important to use the power off button before removing power from the Kiwi as this first halts Debian in a safe fashion that will prevent any possible filesystem corruption.

The Kick button can be used to close all active user connections (i.e. kick everyone off the SDR). This is useful when there are users who have been logged in for a very long period of time.

The Inactivity time limit field can be used to limit the amount of time a user can be connected when not actively changing the SDR controls (i.e. parked on a specific frequency for a long period of time). The timeout period is reset as soon as some adjustment to the controls is made. A value of zero disables any time limit checking. This is the default.

Similarly the 24 hour per-IP address time limit field can be used to limit the amount of time a user from a specific incoming IP address can be connected during a 24 hour time period. This period is independent of the inactivity limit described above. A value of zero disables any checking. This is the default.

connect

The configuration on the connect tab is used to define the URL used to connect to your Kiwi from the local network and, optionally, from the public Internet. Here also is the configuration of the DDNS DUC and reverse proxy as described in the network section of this document.

Config

The sensitivity of your antenna will determine how the base waterfall colors will appear. We suggest changing the Initial waterfall min field to compensate. Here is an example of base waterfall colors that are "washed out" with too much green because the default value of WF min on the main control panel is too low at -110 dBFS: (click for larger)



Here is the same waterfall with WF min set to -80 dbFS: (click for larger)



Once you have found a good value of WF min set that value in the Initial waterfall min field on the Config tab of the admin webpage.

The Max receiver frequency menu allows the top reception frequency to be increased to 32 MHz. This is to accomodate some users who want to down-convert signals into the 30 - 32 MHz region. Note that due to the KiwiSDR ADC clock frequency (66.67 MHz) there will be increased aliasing and spurious responses above 30 MHz.

Configuration when using a down-converter
The Kiwi frequency scale and other places where the frequency appears and is entered can be adjusted to account for any VHF/UHF down-converter (transverter) you have installed ahead of the Kiwi antenna input. The Frequency scale offset (kHz) field is used for this purpose.

Enter the number of kHz necessary to bring the converted frequency to the correct position on the scale. For example to map 50-52 MHz to 28-30 MHz place 22000 kHz in the field (50000 - 22000 = 28000). To map 144-148 MHz to 28-32 MHz set the field to 116000 kHz (144000 - 116000 = 28000) and set the Max receiver frequency menu selection to 32 MHz to get the extended receiver coverage. Inverted tuning when the converter uses a high-side LO is not yet supported (common for 23 cm / 1296 MHz converters).

The Coverage frequency low/high fields on the Public tab help rx.kiwisdr.com use the correct frequency icon if you have listed your Kiwi there. Enter the frequencies covered by your down-converted setup. For example setting 118000 and 138000 in the fields will make rx.kiwisdr.com display the icon "Airband". For other frequencies a frequency range in MHz will be displayed. So if you entered 50000 and 52000 then "50MHz - 52MHz" will be displayed.

The coverage fields can be used even if you are not using a down-converter. Suppose you have a Kiwi specializing in the AM MWBC band with attenuation outside those frequencies. You could set the fields to 540 and 1710 and "0.5MHz - 1.7MHz" would be displayed.

Webpage

Map field
Note: Consider specifying coordinates that don't reveal your exact location. You can get the "Google format" map reference by Googling the name of your location (town etc.), clicking on Google maps from the search result, then clicking on the "share or embed map" item from the Google maps menu at the top left. Place in the Map field the last part of the link that begins with "https://www.google.co.nz/maps/place/" You can use the check map button to verify.

Grid square field
If you are not familiar with grid squares just click on the check grid button. A webpage will appear where you can enter your location name and receive a 6 character grid square identifier to enter in the field.

You can replace the default startup background photo with your own. Scale a photo file (jpeg, png, etc.) to be 350 pixels high. Starting with the v1.17 release there is a "file chooser" dialog so you can download the file to the Kiwi directly using the admin page. Although there is a Photo height field, changing it from 350 pixels currently doesn't work. Change the Photo title and Photo description fields as appropriate for your new photo.

The Owner info field allows you to display a message, including HTML, in the middle part of the top bar. Add your own logo here, short message or maybe a Paypal donation button to help defray your Internet costs for a publicly-accessible Kiwi.

Note that the Title field can contain HTML, like a link, just like the Status field even though there is no preview shown.

Public

Note: Your Kiwi will appear on other sites like rx.linkfanel.net and ve3sun.com/KiwiSDR if it is registered on rx.kiwisdr.com

Note: Consider specifying coordinates that don't reveal your exact location, although the various maps add some dither to the location when zoomed-in as a privacy measure.

Registration on rx.kiwisdr.com
On the Public tab are the parameters for rx.kiwisdr.com registration. No API key is necessary. Just fill-out your listing information (name, location, etc.) and set the register switch to Yes. The registration status field should eventually show a message (this can sometimes take several minutes).

Your kiwi will not be listed unless kiwisdr.com can connect and poll its status periodically. Make sure you have the menu on the admin page, "connect" tab setup correctly for your connection situation. Test it. For example use a cellphone with wifi switched off so your are accessing the Kiwi through the Internet via the cell network instead of locally via the (local) wifi network.

Make sure your location on the various map sites (e.g. rx.linkfanel.net) shows the correct latitude and longitude. A common mistake is not specifying a negative longitude for the Americas or a negative latitude for locations in the southern hemisphere (we've made this mistake ourselves). You can use the check map button to verify. Note that the latitude and longitude are entered as signed decimal degrees, surrounded by parenthesis, e.g. "(-37.631016, 176.172019)". Not hours-minutes-seconds, no "N S E W" notation, no "degree" symbols, etc. If you zoom in you'll notice that the map sites dither the location a fair amount to help protect your privacy.

If the GPS is running, and has a fix, a blue button labeled set from GPS will appear. Use it to fill-out the location field automatically. The same is true for the grid square field.

See Configuration when using a down-converter for a description of how to use the Coverage frequency low/high fields.

DX

The DX tab (not available on mobile devices) controls the content displayed in the DX label and band bar areas above the frequency scale. And also in the "select band" menu on the main control panel. As you make changes they should be immediately reflected in all active user connections (except for file import discussed below which requires a restart).

The Default DX label database menu determines which of the three label databases a user connection will be initially shown: (the user may change the database at any time after) The remainder of this section describes how to edit DX labels in the stored database.

Changes are saved as you type. The message Changes saved will appear when a save occurs.

It is extremely important that you maintain timely backups of the label database. Especially if you've spent many hours carefully curating an extensive, customized set of labels. Use the Export:
JSON
CSV
buttons to download a copy of the labels onto the computer running the browser.

The band bar and select band menu information is stored in the normal Kiwi configuration file. This file is saved, along with everything else, when you make a full system backup to SD card (see admin page "Backup" tab). You could also backup the files individually using a file transfer program such as WinSCP. The files are named:
/root/kiwi.config/dx.json
/root/kiwi.config/kiwi.json
/root/kiwi.config/admin.json

There are four sections that can be shown or hidden using the
+
and
-
buttons on the left. They are:
Stored DX labels Defines the labels themselves.
DX type menu Defines content of Type menu appearing in Stored DX labels section above.
Band bars Defines content of band bars and select band menu on user page.
Band service menu Defines content of Service menu appearing in Band bars section above.

If you hover the mouse over the icon a popup will appear with additional information.

Stored DX labels
The fields are the same as those in the user connection DX label edit panel.

The
+
and
-
buttons will duplicate and delete, respectively, a label entry. The duplicate function allows a new label to be created before the first and after the last existing entries, or anywhere in-between.

The button allows the optional schedule information to be added. If the schedule is the default (always active, 0000 - 2400, 7-days) then the schedule controls are not displayed to save screen space. Use the button to reset the schedule to the default. More information about label schedules.

There are search controls at the top right for the Freq, Ident and Notes fields. A matching field is highlighted in yellow (closest match for frequency). Type the enter/return key to search for the next occurence of the Ident or Note. The searches will wrap. The frequency is in kHz and MHz notation can be used e.g. 7M versus 7000

See the end of this section for a discussion of editing the dx.json file directly.

DX type menu
The Type menu in the Stored DX labels section above has some values associated with the default dx.json file. But just as with the DX labels you can change the type values to be whatever you like.

However, it is important to understand how changing the type values will effect existing labels. If you have labels that use a particular type, let's say using the type menu name associated with the T1 entry on the DX type menu section. And then you clear the Menu entry name field for T1. What should happen to the Type menu? The answer is that a temporary name called, in this case, (T1) appears in the menu to remind you there are still labels using the T1 definition. If you subsequently change the type name to something non-blank the menu and label will follow the change.

You can define up to 14 different type entries. The 15th type is used in implementing masked frequencies and cannot be changed or removed.

The HTML color name field accepts all HTML color name specifications, including by name, hex value (e.g. #6789ab), or specific RGB/HSL value (e.g. hsl(300, 75%, 95%)). Color utilities like HTML color picker or color names by shade are useful.

For reference, the colors used with the EiBi labels are:
cyan hsl(300, 100%, 80%) deepSkyBlue
silver hsl(50, 100%, 70%) peachPuff
mediumAquaMarine hsl(270, 100%, 80%) hsl(180, 100%, 80%)
hsl(70, 100%, 45%) springGreen hsl(0, 100%, 75%)

Band bars
These next two sections control the band bars seen above the DX labels and frequency scale. And also the content of the select band menu in the main control panel.

The order of entries in the band bars section exactly determine the content of the select band menu. So for example it is important that all entries with the same Service type are grouped together so they appear under a single service heading in the menu.

The select band menu can define band bars and also single frequencies commonly used that do not have an associated band bar (e.g. the time stations). For this reason the ITU / Visibility menu contains the two entries show on band scale only and show on band menu only. The other menu entries, including any, always imply the entry will appear on both the band scale and in the band menu. For a single frequency entry set the Min and Max frequency values equal.

The ITU Region 1|2|3 selection filters when the entry will be shown based on the Kiwi ITU region configuration. Note that entries with ITU region specified typically have different values in the Chan field to account for the different channel spacing in those regions.

The Band name value is the name used in the menu and/or band bar. The band bar name is also augmented by the Menu entry name (service name) and optional Long name fields described below.

An entry in the Band freq/mode field sets a specific frequency and mode when a select band entry is selected. For example this is how the time station entries work. You could e.g. use this to select AM mode and a specific frequency in the AMBC band.

It is possible to have Min and Max frequency values in this list larger than 32 MHz for when a frequency offset is being used (i.e. downconverter/transverter operation).

Band service menu
This section defines the Service menu in the preceding section. The HTML color name field has the same specifications as described above. An example of how the resulting band bar will look with the given color and service name appears on the right.

The two name fields here, Menu entry name (service name) and Long name and the Band name in the preceding section are used in slightly different ways to construct naming in the select band menu and the band bars themselves.

Let's consider a service name of Broadcast, a band name of 41m and a long name of Shortwave Broadcast. In the select band menu 41m will appear under the Broadcast heading, along with any other bands with that same service name. The band bar will have a different name depending how wide it is as a function of the current zoom level. At a minimum 41m will be shown (unless the bar is so short that no text fits.) If it fits 41m followed by Broadcast will be shown. But since the long name is not blank in this example 41m followed by Shortwave Broadcast will be the actual name shown.

Editing the dx.json file directly
In some cases it may be easier to make a large number of changes using a text editor on another computer. The Export:
JSON
CSV
and Import:
JSON
CSV
buttons can be used to copy the label database file. Note that as soon as you import (upload) the Kiwi must be immediately restarted (you will be prompted). If any illegal format JSON or CSV is detected in the labels after the restart error messages will appear in the Kiwi log and a count of the number of bad labels will appear on the DX tab. The bad labels are discarded. So to repair you must fix them in the file and import again.

Each JSON file entry has a number of fixed fields followed by some optional parameters.
[ Freq (kHz), "Mode", "Ident", "Notes", { parameters, JSON object } (optional) ]

The parameters can be any combination of:
"Tn":1 Type code linking to a type menu entry, n is 1 to 15.
"T0":1 is always omitted to save file space.
"lo":Hz, "hi":Hz Passband
"o":Hz Offset
"d0":DOW_value Day-of-week schedule value, MTWTFSS = hex bits 0x7f,
example: M_W__SS = 7'b1010011 = 0x53 = 83.
"b0":hhmm, "e0":hhmm Begin and End schedule times (UTC)
"p":"extension" Extension

Some examples:
[ 5000.00, "AMN", "WWV", "time signal" ] Both Ident and Notes fields
[ 7038.60, "USB", "WSPR", "" ] An empty Notes field
[ 8653.00, "USB", "FSK", "", { "T1":1 } ] Type is second entry (T1) in DX type menu
[ 8681.00, "USB", "FAX", "NMC",
 { "lo":800, "hi":2200, "p":"fax" } ]		 Passband: lo=800, hi=2200 Hz
Extension: FAX
[ 2500.00, "AMN", "BPM", "time signal",
 { "b0":730, "e0":100 } ]		 Schedule (UTC): begin=0730, end=0100,
7-days
[ 4458.00, "USB", "XPB", "MFSK",
 { "d0":33, "b0":2050, "e0":2100 } ]		 Schedule (UTC): begin=2050, end=2100,
DOW: Tue,Sun = 7'b0100001 = 0x21 = 33.

Some characters in the string fields (e.g. Ident, Notes) are encoded using a subset of
URL percent (%) encoding. They are listed below. These encodings are used in any exported JSON or CSV files. When you edit a file you must use the encoding, except you can enter UTF-8 characters directly. The UTF-8 will be encoded when the files are imported and subsequently re-exported.
Character(s) % encoding
control
chars		 %00 - %1f Use \n in the Ident or Notes field for a multi-line label.
No reason to use the other control chars.
" %22 Double quote.
% %25
\ %5c
delete %7f No reason to use this.
UTF-8
bytes 		%80 - %ff You can enter UTF-8 characters in your text editor
but they will be encoded when the file is imported
and subsequently re-exported.

For CSV files the semicolon ; is the field separator character. The first line contains a legend describing the order of the fields. To include the double quote character " inside a string field, like the Ident or Notes fields, repeat it twice. This is a standard escape mechanism supported by spreadsheet programs.
For example: Notes field with ""double quotes"" embedded
Or use the %22 encoding for a double quote. When imported, the CSV file is converted to JSON and stored in the usual dx.json file.

Extensions

WSPR
If you don't have a Ham radio callsign, but would like to contribute your Kiwi's WSPR decodes to wsprnet.org, set the Reporter callsign field to something like "SWLRF82". Where "SWL" is the well-known abbreviation for "shortwave listener" and "RF82" is a 4-character grid square describing your Kiwi's general location available from this site. There are other conventions as well, e.g. "SWL/ZL" where "ZL" is a Ham radio callsign prefix for New Zealand.

Security

Public/private channels
On the admin security tab you will find a setting allowing you to disable the password prompt for a subset of the 4 channels (none, 1, 2 or 3) when an overall user password has been set. This allows you to divide the 4 channels into two sets: a publicly-available set requiring no password and a private set requiring a password. Owners of the more popular Kiwis have long complained that the channels are always full and they, or their friends, can never get in without restarting the server and dumping everyone off. It is hoped this feature may persuade some owners of completely closed Kiwis in desirable locations to make some of their channels public.


Controlling the server from a Beagle login

Although most of the control and configuration of the server is accomplished via the admin webpage, there are some shell commands that can be used. Login to the Beagle from another computer using the debian account and obtain a root shell with the command sudo sh. On the other computer use the ssh program with Linux, or PuTTY on Windows. Change to the Beagle_SDR_GPS directory. A shortcut for this is the cdp command alias (change directory project). Once there a number of commands can be used to control the server: Most of these features as also available on the admin webpage. For example the log files can be viewed under the Log tab and the server can restarted with a button on the Control tab.


Special access-related configuration

There are several configuration options related to admin access of the Kiwi. For security reasons these are specified by files in the /root/kiwi.config directory on the Kiwi rather than directly in the web-based admin configuration. The file names and their contents are:

Manual frequency calibration

If your GPS antenna is connected and receiving signals then the KiwiSDR clock frequency will be continuously calibrated automatically. If not you can perform a manual calibration. There are two sources of clock oscillator error. Inherent error due to manufacturing variations and error that changes with the ambient temperature. A manual calibration will correct the inherent error, and error due to the current temperature, but will not track error due to future temperature changes. Follow these steps:

Tune to a station transmitting a carrier on a known, accurate frequency like a time station (WWV 15 MHz in this example). Use the highest frequency station possible as this will show the most offset (i.e. an HF station rather than LF/VLF). Zoom all the way in and select the exact center of the carrier line in the waterfall with the mouse. The yellow vertical bar of the passband should align with the waterfall carrier line. See image below. Note the WWV -/+100 and +600 Hz modulation shown in addition to the carrier (frequency scale ticks are 100 Hz).




Right-click to bring up the menu and select cal ADC clock (admin). You will be prompted for the admin password if necessary. On a laptop there are usually options for generating a right-click if your trackpad doesn't have left/right buttons (i.e. with a two-finger tap, control-tap, etc.)




A confirmation dialog will appear showing how far the clock must be adjusted to get to the nearest 1 kHz. In this case +81 Hz is needed to get the carrier on 15000 kHz. The normalized ADC clock adjustment in parts-per-million (ppm) is shown, 4.9 ppm in this case.




As soon as confirm is clicked the waterfall will shift to reflect the new calibration. This new calibration value will be remembered and applied on every Kiwi restart. It will be reset to zero when GPS corrections are occurring.





Downloading the software onto an SD card

This procedure is normally not necessary since, if you purchased the Kiwi "full" version which includes a BeagleBone Green (BBG), the software is already pre-installed on the BBG. However there are cases where you might want to download the software:
Debian 11 -- BBG/BBB version

If you are reading these instructions because you want to upgrade your Kiwi to Debian 11 then you must follow the detailed instructions given on the Kiwi Forum. Simply following the procedure below is NOT sufficient to fully upgrade to Debian 11. Example: your Kiwi's configuration will not be restored! However, if you are installing the software from scratch (not upgrading) it's fine to use the Debian 11 image with the procedure below.

Debian 9 -- BBAI version

(A Debian 11 image for the BBAI will be released soon)
For BBAI, the flasher image below only restores the BBAI to factory state. No Kiwi software is installed. Follow the procedure on the Kiwi Forum to install the Kiwi software. Be careful: A BBAI-based Kiwi will not run using any other image versions.

Debian 11 -- BBAI-64 version

The BBAI-64 has always used Debian 11. So the flasher image for BBAI-64 is really only useful in a couple of cases: The BBAI-64 uses the arm-64 architecture and not simply the arm architecture of the BBAI and BBG/BBB. Hence the need for a separate image. Be careful: A BBAI-64-based Kiwi will not run using any other image versions.

Procedure:
In case you are unfamiliar with the process of installing software on a Beagle here's how it works. The micro-SD card is what's known as a 'flasher'. Each time you boot your Beagle from the micro-SD card it will copy its contents to the on-board flash memory (eMMC) of your Beagle. In other words all the software previously installed on your Beagle will be
completely overwritten and lost
. So be very careful in using a flasher micro-SD. Remember, the copy operation will only occur when you boot from a micro-SD flasher. It is possible to insert a flasher micro-SD into a running system so that it may be read or re-written like any other card. But be certain to remove it immediately after you're done. Otherwise the next time you reboot the Beagle the flashing operation will begin (if the card is still a flasher). Even we make this mistake occasionally and it is very annoying to lose all your work that is stored on the Beagle's on-board filesystem.

Downloading:
An image file from the Internet must be downloaded and copied to a micro-SD card to turn it into a flasher. This can be done on the Beagle itself running whatever version of Debian Linux happens to be installed. There must be enough filesystem free space for the image file. Use the d. alias to check free space. It is also possible to use programs on Macs and PCs that write image files to micro-SD cards. Proceed as follows.