The KiwiSDR 2 online store is open for orders! Please visit
Today's v1.694 update is hopefully a working version of the failed v1.691,692 release of a few days ago.
See the first post of the "v1.694" thread below for the CHANGE_LOG notes.
Please visit (documentation) and (online store)

Debian 11 upgrade for Kiwis using BeagleBone Green/Black

[updated 14-Mar-24]

It is now okay to use this image to re-flash BBG/BBB based KiwiSDR 1 and KiwiSDR 2 devices.

Instructions here:

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: 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.


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.


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] 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.


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.



  • 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:


    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.


    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 


    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



    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 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 gives numerous ways of determining the ip address. The easiest are described here:

    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" 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.



    Insert backup sd card you made earlier on.


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

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


    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.


    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.



    Start the Kiwi server.


    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: 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 ( 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.

  • edited February 29

    I tried to run two newly purchased BBB boards with the KIWI 2-cape and wasn't able to flash the BBB first with the image that I downloaded above. I unpacked a new BBG that I had in store and it worked straight away. For info: the BBB were also not accessible via USB nor via IP, using Windows 10. Manufacturing date 09/2022....sent them back to my supplier

  • On the BBB I had to hold the boot-button during power on to boot from the card. With the BBG that was not necessary.

  • In general BBB does work. I have one here that I have used recently with this new image file. It's an older Element 14 BBB though.

  • I used the above image file to try and reflash the BBG that shipped with the KIWISDR2, due to an issue when assigning a static IP, and it did not seem to restore default DHCP settings as it would not take an IP address.

    I had an older BBG from the 7 kiwi which i had fitted with a BBAI, and that BBG was able to be re-flashed.

    Is there something that is different about this new BBG board?

  • Upon booting the factory KIWISDR2 all went well.

    After changing from DHCP to static, the connection was lost to the KIWI and the router does not "see" it.

    Factory reflash 3x and router still does not see the kiwi, although there is a link light and what appears to be traffic on the port as it is blinking.

    I took a screen shot before acknowledging the changes, and the Beagle bone can no longer be accessed after these changes were applied.

    I took and older BBG, and flashed using same SD card from above; re-flashed and that BBG is working.

    I will now try to assign a static address to it, and see what happens.

  • jksjks
    edited March 6

    I think there is an interaction issue between new code that puts the Kiwi-1 vs Kiwi-2 model info in the Kiwi's EEPROM versus the age of U-boot on the eMMC of the Beagle.

    It's been extremely difficult for me to diagnose. You have to use a serial console connection because Debian drops into "emergency mode" for reasons I don't understand and the Ethernet interface is left disabled.

    So for now please do not use the Debian 11 image to re-flash anything until I understand what the heck is going on. Thank you.

  • edited March 6

    I was able to load the BBG drivers on a pc and connect via USB to the BBG using putty @

    I am by no means any kind of expert on Debian but this is what i have found so far.

    ifconfig showed that eth0 adapter will not take an IP address.

    Sudo ifconfig [interface_name] [IP_address] results in what appears to be an assigned address, but it does not hold or pass traffic and gets dropped almost immediately.

    It appears the auto eth0 commands are missing as well. Bash error says not found.

    -bash: auto: command not found

    further look, auto is not found in the


    I cannot login as root to the BBG. Serial number, temppwd, and root do not work as the password.

    This was on the BBG that shipped with the new KIWI2, without the KIWI cape after the aforementioned re-flash.

  • jksjks
    edited March 8

    Note that even though I have posted an sd card "EEPROM fixer" (see other thread) that doesn't mean it's safe to use the Debian 11 image to upgrade a Kiwi-1.

    I have pulled the website D11 images, but you could still use the backup function on a working Kiwi to make a D11 card and re-flash a different Kiwi-1, and it might brick. So I need some time to create new D11 images that don't have this problem.

  • Looking at the new BBG I received this morning, I were pondering after reading this thread...

    (for replacement of my kiwi1's BBG due to FPGA not responding issue)

  • It's okay to use this Debian 11.9 / v1.665 based image file.

    Instructions here:

  • Hello,

    I updated my Kiwi from Debian 8 to Debian 11.9 today.

    I wanted to thank you for the excellent instructions on how to perform and transfer the config files.

    Everything worked great.

    Thanks to the Kiwi team👍️

  • Thank you for the confirmation that it worked.

    Usually I only hear when there are problems! lol

  • I am trying to load D11 and this is what I get:

    so as I understand the wget works ok but bash gives an error. Now that I have tried it several times the wget will increase a number (.N) of each download. And If I end the bash comman wiht that same number (.N) it still gives an error.

    My knowledge of Linux is zero so I am depending of written instructions. I can copy-paste without understanding really what I am doing. :)


  • My fault for using such long filenames I suppose. But you've got a typo in the filename.

    You're missing the BBG_BBB part.

  • Indeed, it is missing but I copy-pasted it. 😁

    Will try again in a moment, after sauna.

    Much appreciated, thank you.

    73 Pekka

  • Well, now I get this. What might cause it?

    73 Pekka

  • Aah, forgot to say sudo su. Maybe that...

  • edited April 26

    Hello kiwi user's

    I think I followed the procedure to the letter, and performed the operation several times even with "DD the .img."

    Test with à 4G MSD or a 8G after format each

    Initially my KIWI1 is from 2016 with Debian 8.5. After attempts to upgrade the Debian 11 is installed on the BBG

    I have no connection using " kiwi.local:8073" or ";8073"

    The BBG loops continuously after boot on power-up with a blue fixed led (bit 2) and a blinking one (bit 8).

    Where I did my mistake ?

    Thanks for your help

    73 Rene F6BIR

  • It's progressing but still no connection to the web server

  • May be it can help to debug

Sign In or Register to comment.