Debian 11 (Bullseye) upgrade for Kiwis using BeagleBone Green/Black

[updated 12-Feb-24]

Changes to these instructions will be marked with e.g. "[New]" "[Updated]" etc.


Part 1 of 3

None of the following applies to BeagleBone AI or AI-64 systems. These instructions are for Kiwis using BeagleBone Green or Black ONLY. There is no Debian 11 image for BBAI yet. BBAI-64 has always run Debian 11.

Debian 8, used by the current Kiwi software on BB Green or Black, is no longer receiving security updates. See: www.debian.org/News/2020/20200709 For this reason some of you will be interested in upgrading to a later Debian release.

The Kiwi software has been ported to Debian 11 (Bullseye). But there are some strict requirements that must be met before the upgrade can be performed:

The upgrade process unfortunately cannot be automated. You must have some familiarity working with computers, the Kiwi hardware, Linux and micro sd cards.


Requirements:

Kiwis using the older BeagleBone Black 2GB eMMC (flash memory) model will not work. You will have to upgrade to a 4GB eMMC BB Green or Black. The KiwiSDR kit version always shipped with a 4GB BB Green. So you will only be in this situation if you purchased a Kiwi "board-only" version and supplied your own 2GB BBB. All BBBs produced were 4GB versions starting about 7 years ago. So very few of you should be in this position.

WiFi: If you use an Ethernet-port-to-WiFi adapter (e.g. TPLink TL-WR802N) then you're fine. If you use a USB-WiFi dongle and have made Debian software changes, including configuration changes or special kernel downloads, then you'll have to figure out what to do on Debian 11. We don't support WiFi dongles and this upgrade procedure does not take them into account. It assumes you are using an Ethernet connection (wired or via WiFi adapter).

Ethernet ip address: When the Debian 11 image is installed your Kiwi will revert to getting its ip address from DHCP. If you have setup static ip addressing then there will some complications.

You will need physical access to the Kiwi to install and remove micro SD cards. This may also mean partial disassembly of your particular enclosure to reach the sd card slot on the Beagle.

You should have at least two micro SD cards (8 GB minimum) available.

If you are using the antenna switch extension make a note of the ip address of your switch as you will reinstall the extension as a final step.


Procedure:

Read all of these instructions and make sure you understand them before proceeding. If any of the steps gives you an error message or an unexpected result STOP and ask for help on the Kiwi forum or support email.

Login to the Beagle using ssh or PuTTY

Find a way to login to a Debian shell running on the Beagle. This is not the same as the web-based connection to the Kiwi admin page. It is a text-based connection to Debian/Linux running on the Beagle so you can perform certain operations while the Kiwi software is not running.

From an external PC/laptop you typically use the program ssh from Linux or Mac. From Windows use ssh from the command prompt or the PuTTY program. Use the same name of your Kiwi to connect, but not the Kiwi port number. For example, if you use my_kiwi:8073 to connect from a browser just use the my_kiwi part with ssh/PuTTY. Specify "debian" as the user name, e.g. ssh debian@my_kiwi. You will be prompted for the debian account password. This will either be the Kiwi's serial number, available on the admin page, "network" tab (second line, right) or written on the Kiwi circuit board (or case bottom for KiwiSDR 2). Alternatively the password might be the same as the Kiwi admin password or even "temppwd". If you've ever set a custom root password then that password will probably still be in effect. Obtain a root shell by typing "sudo su".

Make an ssh/PuTTY connection to the Kiwi now. Once connected type the command "dog". You should see output similar to the following:

Debian 8.11 [any value from 8.5 to 8.11 is okay]

BeagleBoard.org Debian Image 2016-05-13

Linux www 4.4.9-ti-r25 #1 SMP Thu May 5 23:08:13 UTC 2016 armv7l GNU/Linux

Leave the connection open. We'll return to it in a later step.


Backup:

Make a full backup of your current Debian 8 system. Go to the admin page, "backup" tab. Insert an sd card (8 GB minimum) into the Beagle's sd card slot. The exposed contacts of the sd card should face away from the bottom of the Beagle circuit board as you insert the card into the slot (this seems counterintuitive). Push the card until it clicks as it locks in place.

Despite the warning shown in the red box about removing the card immediately after the backup completes, leave the card installed for the next step. Click the button "Click to write micro-SD card". The backup should take less than 10 minutes and say "WORKED" in green on the second line, right, if it completes successfully. If it says "ERROR" note the error message in the last few lines of the scrolling text box at the bottom. Try another sd card as they have high failure rates.


Continue with Part 2 in the next post.

Comments

  • jksjks
    edited February 14

    Part 2 of 3

    Verify the Kiwi configuration files were correctly saved

    The Kiwi configuration files saved as part of the backup will be used to restore your Kiwi configuration to the new Debian 11 version. It is very important to check now for their integrity on the backup. Return to the ssh/PuTTY connection and type:

    mmc

    The output should be similar (not exact) to the following. mmcblk1 must be present. It says "29.8G" because a 32 GB SD card was being used.

    NAME  MAJ:MIN RM SIZE RO TYPE MOUNTPOINT

    mmcblk0boot0 179:8 0 2M 1 disk 

    mmcblk0boot1 179:16 0 2M 1 disk 

    mmcblk0 179:0 0 3.7G 0 disk 

    └─mmcblk0p1 179:1 0 3.7G 0 part /

    mmcblk1 179:24 0 29.8G 0 disk 

    └─mmcblk1p1 179:25 0 2.3G 0 part 

    mosd1

    cd /media/sd_boot/root/kiwi.config


    The diff commands should produce no output showing that the files have no differences.

    /usr/bin/diff admin.json ~/kiwi.config

    /usr/bin/diff kiwi.json ~/kiwi.config

    /usr/bin/diff dx.json ~/kiwi.config

    cd

    umsd

    Remove the sd card. Push it into the socket until it clicks and releases. Then you can remove it from the card slot.

    Use the halt command to shutdown Debian and power off the Beagle.


    Prepare the Debian 11 sd card image and re-flash the Beagle

    Use a second sd card for this step (i.e. do NOT use the card you just used for backup above). Use an 8 or 16 GB card if you can. 32 GB and larger cards may or may not work due to booting issues. For 32+ GB cards you will likely have to hold down the Beagle boot button (switch) before power up (release a few seconds after the 4 LEDs first light up).

    Follow these instructions kiwisdr.com/quickstart/index.html#id-net-reflash to place the Kiwi/Beagle-specific Debian 11 image on the card. Use the card to re-flash the Beagle as described in the instructions. Be certain to remove the card after the re-flashing completes and before you power up the Kiwi.


    Establish communication with the Kiwi admin interface

    Determine the (possibly) new local ip address of the Kiwi. Remember that the new Debian 11 image defaults to using DHCP to assign an ip address to the Ethernet port and also defaults to using port 8073. The documentation at kiwisdr.com gives numerous ways of determining the ip address. The easiest are described here: kiwisdr.com/quickstart/index.html#id-just-tell-me

    So if you have been using a static ip address then later on you will have to repeat whatever procedure you used when the Kiwi was first installed to transition from using DHCP to a static ip. Note that if you've setup (in your router) DHCP constant ip assignment via association with the Ethernet MAC address that this will still work. This is because the MAC address is unchanged across Debian upgrades.


    Network software update will be delayed until overnight

    The Debian 11 image contains version v1.661 of the Kiwi software. It is likely the current Kiwi software version is newer than this. During the first overnight period (1 - 5 AM local time) a network update will occur to install the latest version (assuming Internet access etc).


    Continue with part 3 in the next post.

  • jksjks
    edited February 10

    Part 3 of 3

    Restore the configuration to the Kiwi

    At this point the Kiwi server will be running on Debian 11. It is important to stop it before restoring the configuration files. Otherwise a restored file will be immediately overwritten when the Kiwi software decides it has to save a configuration value. Proceed as follows:

    ssh/PuTTY into the Kiwi which is now running Debian 11. Because of tighter security you can no longer login to the root account on a new Debian setup. Use the "debian" user account, e.g. "ssh debian@my_kiwi", "ssh debian@kiwisdr.local", "ssh debian@192.168.1.xxx" etc. The password will always be the Kiwi's serial number since a clean copy of Debian is being used. See the earlier instructions about where to find the serial number.

    Now use the command "sudo su" to obtain a root shell. Use the serial number as password again. A post on the 2nd page of this thread shows how to modify /etc/ssh/sshd_config to enable root logins.

    Stop the Kiwi server.

    cdp

    mst


    Insert backup sd card you made earlier on.

    mmc

    Should show output similar to the following. mmcblk0 must be present.

    Note that the mmc0/mmc1 number is swapped compared to Debian 8!

    NAME  MAJ:MIN RM SIZE RO TYPE MOUNTPOINT

    mmcblk1boot0 179:8 0 2M 1 disk 

    mmcblk1boot1 179:16 0 2M 1 disk 

    mmcblk1 179:0 0 3.7G 0 disk 

    └─mmcblk1p1 179:1 0 3.7G 0 part /

    mmcblk0 179:24 0 29.8G 0 disk 

    └─mmcblk0p1 179:25 0 2.3G 0 part 


    Mount the sd card, copy the configuration files, verify the files, unmount the card.

    mosd0

    cd /media/sd_boot/root/kiwi.config


    Copy the required configuration files.

    cp admin.json kiwi.json dx.json ~/kiwi.config

    diff admin.json ~/kiwi.config

    diff kiwi.json ~/kiwi.config

    diff dx.json ~/kiwi.config


    Copy the optional files. Ignore any error about a particular file being missing.

    cp config.js photo.upload noip2.conf frcp.ini ~/kiwi.config

    cp opt.admin_ip opt.no_console opt.git_no_https ~/kiwi.config


    Unmount the sd card.

    cd

    umsd


    Start the Kiwi server.

    ku


    Your Kiwi should now be running again using your specific configuration.


    Remaining issues

    If you were using the antenna switch extension download the latest version, install and configure per the instructions: github.com/OH1KK/KiwiSDR-antenna-switch-extension Note that the configuration details (antenna names, permissions, frequency offsets) on the admin page, extensions tab, were already saved and restored as part of the Kiwi configuration.

    Use the admin page, network tab, to set an Ethernet static IP address and DNS entries if necessary. Note that when the IP/DNS changes are made the effect is immediate, so you have to reload the admin page at the new address to continue. Same for any ssh connection you have open.


    End of procedure

  • Thanks for the update, greatly appreciated.

    Early January you mentioned that you were planning to update all platforms to Debian 12, is that still valid?

  • jksjks
    edited February 11

    Sorry, I am way behind in forum posts, emails, etc.

    I decided to abandon the idea of using Debian 12 at this time due to risk of it being a new release from the Beagle guys. Already there were some problems with it.

    So now I'll have a Debian 11 release for all platforms. BBAI and BBAI-64 are next as soon as I can finish them.

  • I should also mention that Debian 11 backups should now work. Both with this image and on BBAI-64 running the latest release.

    BBAI-64 has always run D11. And until recently backups didn't work with D11 (and the admin backup tab displayed a message saying so). But this should no longer be the case.

  • @jks

    The linked image (http://kiwisdr.com/files/KiwiSDR_v1.661_BBG_BBB_Debian_11.8.img.xz) seems to be the a beaglebone debian 12.2 image without kiwi software

  • Thanks. Working on it..

  • This new image file should be working: KiwiSDR_v1.663_BBG_BBB_Debian_11.9.img.xz

  • edited February 20

    Is it okay if I create the SD card by downloading the .img.xz and write onto an sd card with dd (after decompressing it into .img of course)? I am running AntiX 23 (a Debian-based distro) here.

  • @Yogicat It worked fine for me with dd.

Sign In or Register to comment.