Difference between revisions of "Zynthian Software"

Latest revision as of 10:37, 24 September 2024

1 Stable ZynthianOS SD-image

Full Version:

Stable ZynthianOS (MD5-sum)

Lite Version (reduced soundfont library):

Stable ZynthianOS (MD5-sum)

2 Testing ZynthianOS SD-image

Full Version:

Testing ZynthianOS - Oram Bookworm 64 (MD5-sum)

Lite Version (reduced soundfont library):

Testing ZynthianOS - Oram Bookworm 64 (MD5-sum)

WARNING!!

The testing version contains new features and a lot of fixes but it could also contain new bugs and unknown issues. It may change without notification. Don't use it for production without deep testing! See below for information on how to choose a version.

3 Unzipping

The file you download is a zip or xz file that must be expanded to get a .img file that can be 'burnt' to the micro-SD card used by the zynthian device (Raspberry Pi). This process differs depending on the operating system you use: windows, mac or linux.

4 Preparing the SD-card

Latest SD-card image weight around 7 GB compressed and around 16 GB unzipped. It includes all the software you need for your zynthian, properly configured for working out-the-box with the latest official kits. After downloading and unzipping the SD-image, you have to write it to a suitable SD-card. You need a good-quality SD-card with a minimum size of 32GB. You can use a bigger one if you like.

You can use Etcher, a free software that works on Mac, Windows and Linux, to write the image into the SD-card. There is a really good manual for this at this link.

If you are a terminal guy, dd or pv will do the task. Don't forget to unmount the SD partition before burning and sync before extracting the card. With root privileges, run something like this:

umount /dev/sdc1
pv 2023-08-25-zynthianos-stable-2308.img > /dev/sdc
sync

or if you are a sudoer:

sudo umount /dev/sdc1
sudo pv 2023-08-25-zynthianos-stable-2308.img > /dev/sdc
sudo sync

Note:

RBPi2 is not longer supported by zynthianOS. If you want to use a RBPi2, you have to build your own SD-image.

5 First Boot

First boot could take some time. Be patient and wait until you see the splash screen with the logo. If you have a recent kit (V3, V4 & V5) and the display remains black after 1 minute, please, re-check the instructions above and re-burn the SD-card again. If this still doesn't work, try with a different SD-card before reporting in the forum. For solving SD-card issues, it could be useful to check the RPi status LEDs.

Once you see the splash screen, it could take some minutes until the system is ready. You deserve a beer, or at least some tea or coffee. When the first-boot process finishes, the zynthian will reboot and you will be in the main menu, ready to play.

6 Configuration instructions

Recent SD-images auto-detect latest official kits V3, V4 & V5. If you are using an older kit or a custom hardware, your first step after booting should be accessing the webconf and configuring your hardware.

For accessing the webconf tool, see here
Once logged-in, go to Hardware -> Kit and select your kit version or "Custom". Click on save button.
Then, if you have a custom hardware configuration, configure each device: Audio, Display, Wiring. Use "Dummies" if you don't use any encoder/switch. Don't forget to save your configuration after each step.
When everything is configured, you can reboot zynthian using the System -> Reboot menu item

7 Choosing a software / firmware version

The image you download will set zynthian to the corresponding version, e.g. if you download the stable image then your zynthian will be configured to use that stable release. You may wish to change from the stable release, for example you may want to test a feature or bug that you have reported or maybe there is a need to protect your system from being updated. Webconf provides a mechanism to change the version under its SOFTWARE => Repositories options. The table below details how each version behaves and gives some hint as to which you may prefer.

zynthian versions
Release type	Example version	Risk level	Description
Stable	zynthian-2409	Safe	The current major release. This is what most users should select and is what each stable release image will be configured for. Only fully tested, stable updates (point releases) will be advertised. If you want to experience the latest fixes and enhancements but want a stable platform, this is recommended. (See point release below for those who want even lower risk.)
Staging	oram	Adventurous	Staging branch is where fixes and enhancements to the current stable release are tested before being released in the next point release. Users who want to use the latest version with fairly low risk and early access to updates may choose this version. If you were using staging before its major release, you will continue with the same update experience but lower risk of breaking.
Point release	zynthian-2409.0	Paranoid	A point release is a specific stable update. Chosing a point release will lock the zynthian to that stable version and will not receive any further updates. For users who have found a version that works and do not want any further changes.
Development	bug/1196_zynaptic	Desperate	A branch that is developing or testing a specific fix or change. This branch may not include other fixes and will ultimately become a dead-end. For developers and users wanting to test a specific development effort.
Next Staging	vangelis	Wreckless	The bleeding edge development for the next major release. This branch will change without warning and may be broken at any time. For developers and the most adventurous users.

8 Build your own SD-image

If you like, you can build your own SD image following these instructions:

Building the SD Image using the Setup Script

Also, you would like to try the new docker-builder (thanks @guysoft!!):

Building Zynthian with Docker

@@ Line 1: / Line 1: @@
-== Official Aruk Buster SD-Images (Buster-based) ==
+== Stable ZynthianOS SD-image ==
-The current official Zynthian SD-Image is called '''Aruk Buster'''. It's almost the same than the stretch-based one, but updated and buster-based. Currently we have a first Release Candidate (RC-1):
+'''Full Version:'''
+ '''[https://os.zynthian.org/zynthianos-last-stable.img.xz Stable ZynthianOS]''' ([https://os.zynthian.org/zynthianos-last-stable.img.xz.md5 MD5-sum])
+'''Lite Version (reduced soundfont library):'''
+ '''[https://os.zynthian.org/zynthianos-last-stable-nosfz.img.xz Stable ZynthianOS]''' ([https://os.zynthian.org/zynthianos-last-stable.img-nosfz.xz.md5 MD5-sum])
- '''[https://os.zynthian.org/2019-09-24-zynthianos-buster-lite-1.0.0-RC1.zip ZynthianOS "Aruk Buster" RC-1]''' ([https://os.zynthian.org/2019-09-24-zynthianos-buster-lite-1.0.0-RC1.zip.md5 MD5-sum])
-Latest nightly builds are quite stable, so '''you should consider using the last one ...
+== Testing ZynthianOS SD-image ==
-'''
-{{NoteBox|Aruk Buster SD-Image is pre-configured for official '''Kit v3'''.}}
-== Legacy Aruk Stretch SD-Images (Stretch-based) ==
+'''Full Version:'''
+ '''[https://os.zynthian.org/test/2024-09-23-zynthianos-bookworm-aarch64-oram-2409.img.xz Testing ZynthianOS - Oram Bookworm 64]''' ([https://os.zynthian.org/test/2024-09-23-zynthianos-bookworm-aarch64-oram-2409.img.xz.md5 MD5-sum])
+'''Lite Version (reduced soundfont library):'''
+ '''[https://os.zynthian.org/test/2024-09-23-zynthianos-bookworm-aarch64-oram-2409-nosfz.img.xz Testing ZynthianOS - Oram Bookworm 64]''' ([https://os.zynthian.org/test/2024-09-23-zynthianos-bookworm-aarch64-oram-2409-nosfz.img.xz.md5 MD5-sum])
-The former official Zynthian SD-Image was called '''Aruk'''. It was based on Raspbian Stretch and the first ZynthianOS SD image built using the [https://github.com/guysoft/CustomPiOS CustomPiOS] system (thanks @guysoft!!):
+<br>
- [https://os.zynthian.org/2019-06-26-zynthianos-stretch-lite-1.0.0-RC3.zip ZynthianOS "Aruk Stretch" RC-3] ([https://os.zynthian.org/2019-06-26-zynthianos-stretch-lite-1.0.0-RC3.zip.md5 MD5-sum])
+{{WarningBox| The testing version contains new features and a lot of fixes but it could also contain new bugs and unknown issues. It may change without notification. Don't use it for production without deep testing! See below for information on how to choose a version.}}
-You shouldn't be using Aruk Stretch without a good reason. We have moved to Buster!!
+<br>
-{{NoteBox|Aruk Stretch SD-Image is pre-configured for official '''Kit v2'''.}}
+== Unzipping ==
+The file you download is a ''zip'' or ''xz'' file that must be expanded to get a ''.img'' file that can be 'burnt' to the micro-SD card used by the zynthian device (Raspberry Pi). This process differs depending on the operating system you use: windows, mac or linux.
+<!--
 == Nightly Build SD-Images ==
-If you really like to be in the cutting edge, try the nightly builds:
+If you like to be in the cutting edge, test the latest features and find the bugs, try the nightly builds:
-  '''[https://os.zynthian.org ZynthianOS nightly builds]'''
+  '''[https://os.zynthian.org ZynthianOS Nightly Builds]'''
 Our nightly build system is based on the fantastic work of @guysoft, the [https://github.com/guysoft/CustomPiOS CustomPiOS] system:
@@ Line 29: / Line 35: @@
   ''CustomPiOS is a Raspberry Pi and other ARM devices distribution builder. CustomPiOS opens an already existing image, modifies it and repackages the image ready to ship.''
- '''@guysoft has largely contributed to the project by configuring and setting up the ZynthianOS build server. Really big thanks!!
+'''@guysoft has largely contributed to the project by configuring and setting up the ZynthianOS build server. Really big thanks!!'''
-'''
+-->
 == Preparing the SD-card ==
-Current images are 8GB compressed image file compiled for Raspberry Pi 3. These SD card images include all the Zynthian software, properly configured for working with the official kits. Completely ready to use. Plug and play!
+Latest SD-card image weight around 7 GB compressed and around 16 GB unzipped. It includes all the software you need for your zynthian, properly configured for working out-the-box with the latest official kits.
+After downloading and unzipping the SD-image, you have to write it to a suitable SD-card. You need a good-quality SD-card with a '''minimum size of 32GB'''. You can use a bigger one if you like.
+You can use [https://etcher.io/ Etcher], a free software that works on Mac, Windows and Linux, to write the image into the SD-card. There is a really good manual for this at [https://www.raspberrypi.org/documentation/installation/installing-images/ this link].
+If you are a terminal guy, ''dd'' or ''pv'' will do the task. Don't forget to ''unmount'' the SD partition before burning and ''sync'' before extracting the card. With root privileges, run something like this:
+ umount /dev/sdc1
+ pv 2023-08-25-zynthianos-stable-2308.img > /dev/sdc
+ sync
+or if you are a ''sudoer'':
+ sudo umount /dev/sdc1
+ sudo pv 2023-08-25-zynthianos-stable-2308.img > /dev/sdc
+ sudo sync
+{{NoteBox|RBPi2 is not longer supported by zynthianOS. If you want to use a RBPi2, you have to build your own SD-image.}}
+<br>
+== First Boot ==
+First boot could take some time. Be patient and wait until you see the splash screen with the logo. If you have a recent kit (V3, V4 & V5) and the display remains black after 1 minute, please, re-check the instructions above and re-burn the SD-card again. If this still doesn't work, try with a different SD-card before reporting in the [https://discourse.zynthian.org forum]. For solving SD-card issues, it could be useful to [https://raspberrytips.com/green-and-red-light-on-raspberry-pi check the RPi status LEDs].
+Once you see the splash screen, it could take some minutes until the system is ready. You deserve a beer, or at least some tea or coffee. When the first-boot process finishes, the zynthian will reboot and you will be in the main menu, ready to play.
+<br>
+== Configuration instructions ==
+Recent SD-images auto-detect latest official kits V3, V4 & V5. If you are using an older kit or a custom hardware, your first step after booting should be accessing the webconf and configuring your hardware.
+* For accessing the webconf tool, [[Accessing_Zynthian_from_your_computer#Accessing_the_Web_Configuration_Tool|see here]]
+* Once logged-in, go to Hardware -> Kit and select your kit version or "Custom". Click on save button.
+* Then, if you have a custom hardware configuration, configure each device: Audio, Display, Wiring. Use "Dummies" if you don't use any encoder/switch. Don't forget to save your configuration after each step.
+* When everything is configured, you can reboot zynthian using the System -> Reboot menu item
+<br>
-After downloading the SD-image, you have to write it to a SD-card. You need a SD card with a '''minimum size of 16GB''', although you can use a bigger one if you want.
+== Choosing a software / firmware version ==
-Use [https://etcher.io/ Etcher] (free software works on Mac, Windows or Linux) to write the image onto the SDcard. Or do it manually! There is a really good manual for this at [https://www.raspberrypi.org/documentation/installation/installing-images/ this link].
+The image you download will set zynthian to the corresponding version, e.g. if you download the stable image then your zynthian will be configured to use that stable release. You may wish to change from the stable release, for example you may want to test a feature or bug that you have reported or maybe there is a need to protect your system from being updated. Webconf provides a mechanism to change the version under its SOFTWARE => Repositories options. The table below details how each version behaves and gives some hint as to which you may prefer.
-{{NoteBox|RBPi2 is not currently supported by the latest official zynthian SD images, so if you want to use a RBPi2, you may need to build your own SD image.}}
+{| class="wikitable"
+|+ zynthian versions
+|-
+! Release type !! Example version !! Risk level !! Description
+|-
+| Stable || zynthian-2409 || Safe || The current major release. This is what most users should select and is what each stable release image will be configured for. Only fully tested, stable updates (point releases) will be advertised. If you want to experience the latest fixes and enhancements but want a stable platform, this is recommended. (See point release below for those who want even lower risk.)
+|-
+| Staging || oram || Adventurous || Staging branch is where fixes and enhancements to the current stable release are tested before being released in the next point release. Users who want to use the latest version with fairly low risk and early access to updates may choose this version. If you were using staging before its major release, you will continue with the same update experience but lower risk of breaking.
+|-
+| Point release || zynthian-2409.0|| Paranoid || A point release is a specific stable update. Chosing a point release will lock the zynthian to that stable version and will not receive any further updates. For users who have found a version that works and do not want any further changes.
+|-
+| Development || bug/1196_zynaptic || Desperate || A branch that is developing or testing a specific fix or change. This branch may not include other fixes and will ultimately become a dead-end. For developers and users wanting to test a specific development effort.
+|-
+| Next Staging || vangelis || Wreckless || The bleeding edge development for the next major release. This branch will change without warning and may be broken at any time. For developers and the most adventurous users.
+|}
-== Build your own image ==
+== Build your own SD-image ==
 If you like, you can build your own SD image following these instructions: