Changes

=== How is code of the zynthian maintained? ===

=== How is code of the zynthian maintained? ===

You can log onto a Zynthian itself as the root user if you have the password (it's set to raspberry, pre version 5 and is now opensynth), but you might well change it on a performance machine. People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....  

You can log onto a zynthian itself as the root user if you have the password (opensynth), but you might well change it on a performance machine. (You may wish to avoid developing on your performance machine!) People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....  

[[File:A-terminial-sshing.png|600px|center| An ssh terminal from a host computer (not necessarily yours ....]]

[[File:A-terminial-sshing.png|600px|center| An ssh terminal from a host computer (not necessarily yours ....]]

You and they (if you haven't changed the password)  can, and do pretty much anything you want as it it nothing more or less than a raspberry Pi of various vintages running an operating system. So you can edit files to your hearts content and very quickly render your Zynthian unplayable if you don't know what you are doing.

You and they (if you haven't changed the password)  can, and do pretty much anything you want as it it nothing more or less than a Raspberry Pi of various vintages running an operating system. So you can edit files to your heart's content and very quickly render your zynthian unplayable if you don't know what you are doing.

There is an entire linux world built around what is called a terminal, which contains a command line that you literally type commands into and press enter to get them todo things. Zynthian has one of these,  

There is an entire Linux world built around what is called a terminal, which contains a command line that you literally type commands into and press enter to get them todo things. zynthian has one of these, and there are code editors that operate entirely around the command line, allowing you to change the contents of files on the machine.

and there are code editors that operate entirely round the command line, allowing you to change the contents of files on the machine.

Here, there is no protection. It's your machine and you can break it as you wish, and whilst you will almost certainly get help on the discourse forum, this is not the sort of activity to indulge in twenty five minutes before your performance. It easy to become the essential technician beloved and feared in equal measure, but probably the first concept to learn is the stable branch...

 

Here there is no protection. it's your machine and you can break it as you wish, and whilst you will almost certainly get help on the discourse forum, this is not the sort of activity to indulge in twenty five minutes before your performance. It easy to become the essential technician beloved and feared in equal measure, but probably the first concept to learn is the stable branch . . .  

==== So what is a branch? ====

==== So what is a branch? ====

It's a slightly different version of the code files that a programme running on the zynth keeps track of, allowing you to move around between your different versions and accept of reject changes you have made.  This all operates under a programme of some renown and reputation called git, which was written by the same bloke who was largely responsible for the Linux code base, which is used to house the linux code base itself, you are building on the work of giants. ... and riban.

It's a slightly different version of the code files that a program running on the zynth keeps track of, allowing you to move around between your different versions and accept of reject changes you have made.  This all operates under a programme of some renown and reputation called ''git'', which was written by the same bloke who was largely responsible for the Linux code base, which is used to house the Linux code base itself, you are building on the work of giants (... and riban).

There are many, many introductions to git [https://docs.github.com/en/get-started/getting-started-with-git Getting started with git] and it has a certain reputation for complexity, but it rigorously hangs on to any code it is asked to look after even thou' this can be a mixed blessing if you are messy as I am. But it can be operated from the command line but it's better to use an IDE (Integrated Development Environment) which makes it all push button, more on this later.  

There are many, many introductions to git [https://docs.github.com/en/get-started/getting-started-with-git Getting started with git] and it has a certain reputation for complexity, but it rigorously hangs on to any code it is asked to look after even thou' this can be a mixed blessing if you are as messy as I am. But it can be operated from the command line but it's better to use an IDE (Integrated Development Environment) which makes it all ''push button'', more on this later.  

Git also works peer to peer. This simply mean that rather than some of the older repository managers, every git instance running on a machine has a similar level of importance to every other, so you don't need a running central server to allow you to operate. That is a big feature that you don't appreciate until you DO work with the mega server in the middle with all it's associated limitations.

Git also works peer to peer. This simply mean that rather than some of the older repository managers, every git instance running on a machine has a similar level of importance to every other, so you don't need a running central server to allow you to operate. That is a big feature that you don't appreciate until you DO work with the mega server in the middle with all it's associated limitations.

This doesn't mean there isn't a a central repository where all the good stuff lives but it does mean that git allows you to make your own little development world where you do no damage to anybody else and you get all the control of being able to set up branches that are differing version of the code

This doesn't mean there isn't a central repository where all the good stuff lives but it does mean that git allows you to make your own little development world where you do no damage to anybody else and you get all the control of being able to set up branches that are differing version of the code and have access to its full history whilst offline.

==== Is Stable the best Branch to use? ====

==== Is Stable the best Branch to use? ====

Stable is the particular branch of code that is know good and behaves in a fashion that will match the documentation.

Stable is the particular branch of code that is know good and behaves in a fashion that will match the documentation.

It wont be cutting edge, but it will behave itself, precisely as you expect, during the performance so this is what you should be initially taking on stage.  

It wont be cutting edge, but it will behave itself, precisely as you expect during the performance so this is what you should be initially taking on stage.  

The good news is if you can get enough of a zynthian running to open up it's inbuilt webserver, forever known as ''webconf'' in these parts, you can select an option that will allow you to return to the stable state.

 

The good news is if you can get enough of a Zynthian running to open up it's inbuilt webserver, forever known as webconf in these parts, you can select an option that will allow you to return to the stable state.

[[File:Zynthian software repositories.png|600px|center]]

[[File:Zynthian software repositories.png|600px|center]]

In the above example, where a little development is being done, the zynthian-ui ( the main zynthian code that controls the Touchscreen display and the main audio and midi functionality is set to another branch. Selecting the stable check box will get you back to your stable structure, and not destroy your edited code in this separate 'branch' called DUO Piano code if you have behaved properly in setting this up.

Changing the zynthian-ui (the main zynthian code that controls the touchscreen display and the main audio and midi functionality) branch from stable to another branch and running update will get you to your desired 'branch'. Repeating in reverse to get back to stable version protects your git-committed changes but hides them and returns you to a working stable version.

This is your protection from your own misdeeds with code. In fact it is sensible to keep at least two ssd's with a known good stable version on so you can give the zynth a brain change and keep a separate ssd for your code projects, but if you trash a part of webconf, then you have little or no easy way onto the machine, and you will need your backup... You have been warned!

This is your protection from your own misdeeds with code. In fact it is sensible to keep at least two uSD cards with a known good stable version on so you can give the zynth a brain change and keep a separate uSD card for your code projects, but if you trash a part of webconf, then you have little or no easy way onto the machine, and you will need your backup... You have been warned!

So now we know how to switch between different branches of code how do we actually set up this new branch?  

So now we know how to switch between different branches of code how do we actually set up this new branch?  

Is there some magic software tool...?

Is there some magic software tool...?

==== Who or what is oram? ====

==== Who or what is Oram? ====

[https://en.wikipedia.org/wiki/Daphne_Oram She was a person, Daphne Oram.]   At the time of the version 5 release we became a little more structural about our branches and whilst stable was maintained an awful lot of new development was done on a branch called oram. Simply named that so it could be referred to easily in the forum without loosing ourselves into version numbers and other such confusions.Many new features appeared under this branch and it was so successful we unofficially moved to it as the new stable until it was promoted to actually be the new stable branch. Once that got to a state for release, we moved into testing and that is the situation as at 05/10/2024 ( that's an UK date, sorry Americans). However new features appear and to seperate this development from the oram branch we now have a branch called Vangelis.  

On 28th September 2024 we released a new stable version: zynthian_2409 which we gave the codename "Oram" to honour [https://en.wikipedia.org/wiki/Daphne_Oram Daphne Oram], a pioneer of electronic sound and music. The ''oram'' git branch is the current stable release version which only changes when there is a ''point release'' (periodic update to deliver feature enhancement and bug fixes) or when there is a ''hotfix'' (urgent bug fixes). This is the version of zynthian that most users should use.

If we get this right we will finally end up with a branch named after a zynthian user and it will all get needlessly messianic and meta.  

 

There is a git branch called ''vangelis'' (named after the wonderful Greek electronic music composer, [https://en.wikipedia.org/wiki/Vangelis Vangelis]) which is used to validate and test further development and bug fixes.

 

(If we get this right we will finally end up with a branch named after a zynthian user and it will all get needlessly messianic and meta.)

==== So what is an IDE ?====

==== So what is an IDE ?====

We could operate all of this using the commaand line and git commands, but unless you really want to, don't. Use an IDE.

We could operate all of this using the command line and git commands, but unless you really want to, don't. Use an IDE.

an IDE (Integrated Development Environment) is a collection of programmes that work together to ease the difficulties of acquiring, writing, modifying, testing, debugging code you write along with the possibility of many, many other functions you probably never considered. At the moment there is one that seems to be really sweeping the board with this ( yes, i know, emacs users, but I worked on pycharm and intellij and I know which I prefer out of the three).

An IDE (Integrated Development Environment) is a collection of programs that work together to ease the difficulties of acquiring, writing, modifying, testing and debugging code that you write along with the possibility of many, many other functions you probably never considered. At the moment there is one that seems to be really sweeping the board with this (yes, I know, emacs users, but I worked on pycharm and intellij and I know which I prefer out of the three).

It's Microsoft's Visual Studio code,  https://code.visualstudio.com/ know to friends and enemies alike as VSC.

It's Microsoft's Visual Studio code,  https://code.visualstudio.com/ know to friends and enemies alike as VSC (or VSCode).

[[File:Zynthian-visual-studio-code.png|600px|center]]

[[File:Zynthian-visual-studio-code.png|600px|center]]

==== So what is a host machine? ====

==== So what is a host machine? ====

Visual studio code is a considerable piece of software, Microsoft know an awful lot about writing code and they have realised presenting an suberb, well maintained IDE into the hands of absolutely anybody with a desire to write code. If you date back far enough to remember "a computer on every desk running Microsoft software" you might generate a rye smile at this point, but the software world is a very different place now, and Microsoft are perfectly willing to produce their IDE for every conceivable platform and operating system they come across and make it work. Anyone who plays around with Arduino's and such will find vsc's platformIO plugin is a considerable improvement on the Arduino's own IDE, and plugins like this are the secret of VSC. The Python environment is a plugin, tools to view git repositories are a plugin, remote access components are a plug in . I haven't looked but I don't doubt there is something MIDI related plugin out there . . .  

Visual Studio Code is a considerable piece of software, Microsoft know an awful lot about writing code and they have placed a suberb, well maintained IDE into the hands of absolutely anybody with a desire to write code. (If you date back far enough to remember "a computer on every desk running Microsoft software" you might generate a rye smile at this point, but the software world is a very different place now, and Microsoft are perfectly willing to produce their IDE for every conceivable platform and operating system they come across and make it work. Anyone who plays around with Arduinos and such will find VSC's platformIO plugin is a considerable improvement on the Arduino's own IDE, and plugins like this are the secret of VSC.) The Python environment is a plugin, tools to view git repositories are a plugin, remote access components are a plugin. I haven't looked but I don't doubt there is some MIDI related plugin out there...  

So we have a considerable chunk of code to run, which we are going to use to write a considerable chunk of code on a Raspberry Pi... Can you run VSC on a Raspberry Pi? Well yes you can, indeed I have run my vsc environment on a Pi4. But I wouldn't run zynthian and the VSC code on a zynthian. There is a cleverer way. You use the remote connection plugin, to access a separate Zynthian doing musical stuff. The vsc remote component installs itself onto the pi, once you present it with the correct password ( Did I mention about getting your passwords sorted out...?), and it handles many, many areas of this process that you can lose yourself into setting up yourself. I have written this process up for other environments and it was ..... Involved. OK vsc advert over.  

So we have a considerable chunk of code to run, which we are going to use to write a considerable chunk of code on a Raspberry Pi... Can you run VSC on a Raspberry Pi? Well yes you can, indeed I have run my VSC environment on a Pi5. But I wouldn't run zynthian and the VSC core UI code on a zynthian. There is a cleverer way. You use the remote connection plugin, to access a separate zynthian doing musical stuff. The VSC remote component installs itself onto the Pi, once you present it with the correct password (Did I mention about getting your passwords sorted out...?), and it handles many, many areas of this process that you can lose yourself into setting up yourself. I have written this process up for other environments and it was..... Involved. OK VSC advert over.  

So Our development environment consists of two machines, one is the zynthian itself, and the other is another computer running the vsc code.  

So our development environment consists of two machines, one is the zynthian itself, and the other is another computer running the VSC GI code.  

This other machine is the host computer and it can be any number of bizarre, powerful, stylish, home built, clapped out, PC's and goodness knows what else, but as long as it runs VSC you are good to go. As I say my host machine is now a Pi5 running VSC very effectively, but your's could be MAC or a PC or goodness knows what else. This is why using a specific IDE provides dividends because we don't need to explain all the different access mechanisms for all these machines. Look up how you install VSC on your host machine and do that. It's pretty easy and if anyone wants to write up specific versions then great! just say so on the forum.

This other machine is the host computer and it can be any number of bizarre, powerful, stylish, home built, clapped out, PC's and goodness knows what else, but as long as it runs VSC and has a network connection you are good to go. As I say my host machine is now a Pi5 running VSC very effectively, but your's could be MAC or a PC or goodness knows what else. This is why using a common IDE provides dividends because we don't need to explain all the different access mechanisms for all these machines. Look up how you install VSC on your host machine and do that. It's pretty easy and if anyone wants to write up specific versions then great! Just say so on the forum.

==== How do I install VSC on my host machine? ====

==== How do I install VSC on my host machine? ====

[[File:Microsft-vsc-download page.png|600px|thumb|center|VSC Download Page]]

[[File:Microsft-vsc-download page.png|600px|thumb|center|VSC Download Page]]

This will download the selected version and you install as appropriate to your operating system. ON my Pi5 I open the download folder  

This will download the selected version and you install as appropriate to your operating system. On my Pi5 I open the download folder  

<br clear=all>

<br clear=all>

[[File:Visual-studio-code-menu-item.png|600px|thumb|center|Pi Desktop VSC menu item]]

[[File:Visual-studio-code-menu-item.png|600px|thumb|center|Pi Desktop VSC menu item]]

simply pressing on the icon will run Visual Studio Code, but for the moment there is a bit more to consider...

Simply pressing on the icon will run Visual Studio Code, but for the moment there is a bit more to consider...

<br clear=all>

<br clear=all>

==== Where are the zynthian source files located on a zynthian? ====

==== Where are the zynthian source files located on a zynthian? ====

The zynthian software exists as a set of directories ( or folders if you prefer) in a directory on the zynthian called ...../zynthian.  

The zynthian software exists as a set of directories (or folders if you prefer - but get used to us using the more accurate "directories") within a directory on the zynthian called... /zynthian.  

[[File:Zynthian-home-directory.png|600px|thumb|center|Zynthian home directory]]

[[File:Zynthian-home-directory.png|600px|thumb|center|Zynthian home directory]]

<br clear=all>

<br clear=all>

The GUI software running on the zynth that operates the touchscreen are located within the zynthian ui directory. and there is a file called zynthian.sh. This is a shell script which isn't written in python but in a language, generally called shell script. It is a collection of commands one runs on the terminal we mentioned earlier an allows various things to be configured, before the actual python script that does the work, which is called zynthian_main.py, is run.  

The GUI software running on the zynth that operates the touchscreen are located within the zynthian-ui directory. and there is a file called zynthian.sh. This is a shell script which isn't written in python but in a ''bash''. It is a collection of commands one runs on the terminal we mentioned earlier an allows various things to be configured, before the actual python script that does the work, which is called zynthian_main.py, is run.  

[[File:Zynthian-ui-folder.png|600px|thumb|center|Zynthian-ui directory]]

[[File:Zynthian-ui-folder.png|600px|thumb|center|Zynthian-ui directory]]

One of the main things the shell script set up is the debugging level which decides what level of message the zynthian generates when it encounters a logging command in the python script. . .

One thing the shell script sets up is the debugging level which decides what level of message the zynthian generates when it encounters a logging command in the python script...

<br clear=all>

<br clear=all>

==== What happens if zynthian crashes and how do I stop it restarting on errors ? ====

==== What happens if zynthian crashes and how do I stop it restarting on errors ? ====

When a zynthian starts up, most of the early functions and what gets run gets handled by a linux tool called systemd. This organises what order things happen in and nursemaids programmes, setting up procedures for what to do when programmes crash or misbehave. For instance there is no point in starting up the network devices if there is no network, and this is the sort of thing systemd does on your behalf. In the zynthian case it starts up the zynthian programme using the scripts we discussed in /zynthian/zynthian-ui and handles a zynthian by restarting the GUI if the software crashes for some reason. This is what you want if you are performing but is decidedly irritating if you are trying to write and test code.  

When a zynthian starts up, most of the early functions and what gets run gets handled by a Linux tool called systemd. This organises what order things happen in and nursemaids programs, setting up procedures for what to do when programs crash or misbehave. For instance there is no point in starting up the network devices if there is no network, and this is the sort of thing systemd does on your behalf. In the zynthian case it starts up the zynthian program using the scripts we discussed in /zynthian/zynthian-ui and handles a zynthian by restarting the UI if the software crashes for some reason. This is what you want if you are performing but is decidedly irritating if you are trying to write and test code.  

There are magic incantations to control zynthian via systemd  

There are magic incantations to control zynthian via systemd  

==== How do I start a X11 windows server so I can run the code in a debugger? ====

==== How do I start a X11 windows server so I can run the code in a debugger? ====

Once you have stopped the zynthian process you can start it within the VSC debugger which is a good thing, but to allow this to happen you have to start the X11 Windows server to allow you to have something to connect to.

Once you have stopped the zynthian process, the GUI layer (X11) required to run zynthian is also stopped so you can start zynthian within the VSC debugger. To allow this to happen you have to start the X11 system to allow you to have something to connect to.

To do this in the window you typed systemctl stop zynthian type

To do this in the window you typed "systemctl stop zynthian", type

  X -r -s 0

  X -r -s 0

You can then start the Debugger in VSC.

You can then start the debugger in VSC.

=== How do I Debug a Zynthian? ===

=== How do I Debug a Zynthian? ===