= *USBSID-Pico software manual*
:author: LouD
:description: This document contains consice information for some of the software supporting USBSID-Pico
:url-repo: https://www.github.com/LouDnl/USBSID-Pico
:revdate: {localdate}
:hide-uri-scheme:
:toc:
:toclevels: 4
:toc-placement!:

Author: {author} - generated on {revdate}

toc::[]
[%always]
<<<

== Disclaimer
include::disclaimer.adoc[]

== Supported platforms
_In active development_ +
*Linux:* Vice, JSidplay2, SidplayFp, RetroDebugger, SidBerry, USB Midi, WebUSB & ASID (in webbrowser) SID Play +
*Windows:* Vice, JSidplay2, SidBerry, USB Midi, WebUSB & ASID (in webbrowser) SID Play +
*Android:* USB Midi, WebUSB & ASID (in webbrowser) SID Play +
*Amiga:* PlaySID library

== Drivers

=== Linux Udev rules
In the https://github.com/LouDnl/USBSID-Pico/blob/master/examples/udev-rules/[examples/udev] directory you can find the https://github.com/LouDnl/USBSID-Pico/blob/master/examples/udev-rules/69-usbsid-permissions.rules[udev rules] that I use on Linux. +
This purely an example file that you can use and change to your own needs.
Steps required for this to work
[source,bash]
----
# Check if you are in the plugdev group with the groups command
groups
# If not, add yourself to the plugdev group, then log out and in
sudo usermod -aG plugdev $USER
# Copy the udev ules file to the correct directory
sudo cp 69-usbsid-permissions.rules /etc/udev/rules.d
# Now reload the udev rules
udevadm control --reload-rules && udevadm trigger
# Not working? Try reloading the service
sudo systemctl restart udev
----

=== Windows driver
Use https://zadig.akeo.ie/[Zadig] to install the correct driver. Replace the driver for `USBSID-Pico Data` with WinUSB. +
image:images/software/zadig-list-all-devices.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/zadig-list-all-devices.png",width="400"]
image:images/software/zadig-install-driver.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/zadig-install-driver.png",width="400"] +

=== Test and configure
After setting up your linux udev rules or Windows driver check, configure and test your board on the https://usbsid.loudai.nl/?player=webusb[USBSID] config tool website +
image:images/software/usbsid-config-connect.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/usbsid-config-connect.png",width="400"]
image:images/software/usbsid-config-checkversion.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/usbsid-config-checkversion.png",width="400"] +
_For more information on how to configure your board, please refer to the https://github.com/LouDnl/USBSID-Pico/blob/master/doc/USBSID-Pico-firmware-manual.adoc[Firmware manual]_

[%always]
<<<

== Supported software
Each section covers the basic use of USBSID-Pico with the software under that section. For more in depth information please refer to the repective website and or github repo of the software.

=== Deepsid
On the https://deepsid.chordian.net/[deepsid] website you can select `WebUSB (Hermit)` or `ASID (MIDI)` for playing PSID files using a supported browser. +

*WebUSB*: After selecting `WebUSB (Hermit)` you need to click the `CONNECT` button and select USBSID-Pico in the pop-up window. Due to the autoplay feature of Deepsid, you might have to press `STOP` a couple of times before the `CONNECT` button will work.

*ASID*: After selecting `ASID (MIDI)` you need to select USBSID-Pico in the dropdown box next to the line that says `MIDI port for ASID`. It might require refreshing the page a couple of times for the box to be filled with midi devices. +
Supported browsers: +

- *Firefox* supports ASID.
- *Chrome* supports both WebUSB and ASID.
- *Edge* supports both WebUSB and ASID.

[%always]
<<<

=== SidBerry
https://github.com/LouDnl/SidBerry[SidBerry] supports PSID files only and can play SID files on USBSID-Pico via CDC (default) or on ASID supporting players via command line arguments. +
General Linux usage:
[source,bash]
----
# to play sidfile.sid on USBSID-Pico
usbsidberry path/to/sidfile.sid
# to detect and print available midi devices
usbsidberry -midi
# to play sidfile.sid via ASID on USBSID-Pico where `1` is the respective port of the ASID device
usbsidberry -asid 1 path/to/sidfile.sid
----
Basic Windows usage:
[source,powershell]
----
# to play sidfile.sid on USBSID-Pico
usbsidberry.exe path/to/sidfile.sid
# to detect and print available midi devices
usbsidberry.exe -midi
# to play sidfile.sid via ASID on USBSID-Pico where `1` is the respective port of the ASID device
usbsidberry.exe -asid 1 path/to/sidfile.sid
----

[%always]
<<<

=== Vice
This section covers the use of USBSID-Pico with Vice under Linux, Windows and MacOS for the GTK and SDL2 versions of `vsid` and `x64sc`

WARNING: Switching on readmode and then switching it off again without restarting the PCB and Vice _will_ result in distorted audio

==== Command-line arguments
Command-line arguments override any previously configured items in your `vicerc` config file. +
All three OS support the same command-line arguments for both `vsid` and `x64sc`. +
However, the sound device argument is OS specific and `vsid` supports a maximum of 3 SID chips +
*Note* that if you define extra SID's and their addresses, these addresses need to point to the required address for the SID tune or Software you want to use. The Vice USBSID-Pico driver will automatically convert each write to the in firmware configured SID chip. +
Below is an excerpt from the Vice manual with information about each command-line option
[source,shell]
----
-usreadmode <0 or 1>
    Enable USBSID-Pico read mode. When enabled, this mode allows for reading from SID registers that provides a means to configure an FPGASID that is seated on USBSID-Pico. This mode is not suited for regular audio use as it disables cycle exact writing & digiplay. Default is (SidUSBSIDReadMode=0) for off, (SidUSBSIDReadMode=1) for on. 

-usaudiomode <0 or 1>
    Set USBSID-Pico PCB (v1.3) audio mode to Stereo or Mono. When enabled the audio of SID socket 1 will be output over the left audio channel and the audio of SID socket 2 over the right channel of USBSID-Pico's audio out. Default is (SidUSBSIDAudioMode=0) for Mono, (SidUSBSIDAudioMode=1) for Stereo. 

-usdiffsize <number divisable by 8>
    Specifies the minimal difference in bytes to use between the head and tail of the drivers ringbuffer, this allows for some audio quality tuning on slower systems. In most cases the default value of 64 bytes (also the size of a USB packet) is the right setting for best audio quality. (SidUSBSIDDiffSize=32-256). 

-usbuffsize <number divisable by 8>
    Specifies the size in bytes to use as ringbuffer to store temporary data when sending SID writes to USBSID-Pico, this allows for some audio quality tuning on slower systems. In most cases the default value of 8192 bytes is the right setting for best audio quality. (SidUSBSIDBufferSize=512-16384). 
----

[%always]
<<<

==== x64sc GTK
ALT+O or click Preferences/Settings to open the settings menu. +
*Sound configuration* +
The sound configuration will require tuning for the computer you use it on. +
In the screenshot below you can see that for this system I use the `pulse` audio driver and have the `Buffer size` set to 1 millisecond and `Fragment size` set to very small. +
These 3 settings can make or break the audio quality. +
image:images/software/x64sc-soundsettings-linux-gtk.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/x64sc-soundsettings-linux-gtk.png",width="600"] +
*SID configuration* +
For any audio to come out of the board you _need_ to select USBSID-Pico as SID engine. +
If you want to use more the one SID then you need to select the amount of `Extra SIDs` and set their I/O addresses. +
image:images/software/x64sc-sidsettings-linux-gtk.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/x64sc-sidsettings-linux-gtk.png",width="600"]

[%always]
<<<

==== x64sc SDL2
Press F12 (Linux/Windows) / F10 (MacOs) to open the settings menu. +
*Sound configuration* +
The sound configuration will require tuning for the computer you use it on. +
In the screenshot below you can see that for this system I use the `pulse` audio driver and have the `Buffer size` set to 25 milliseconds and `Fragment size` set to very small. +
These 3 settings can make or break the audio quality. +
image:images/software/x64sc-soundsettings-linux-sdl2.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/x64sc-soundsettings-linux-sdl2.png",width="600"] +
To get to these settings follow the following settings path: +
`Sound settings` => `Output driver` => Select the driver you want to use +
`Sound settings` => `Buffer size` => Select the milliseconds you want to use +
`Sound settings` => `Fragment size` => Select the size you want to use +
*SID configuration* +
For any audio to come out of the board you _need_ to select USBSID-Pico as SID engine. +
If you want to use more the one SID then you need to select the amount of `Extra SIDs` and set their I/O addresses. +
image:images/software/x64sc-sidsettings-linux-sdl2.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/x64sc-sidsettings-linux-sdl2.png",width="600"] +
To get to these settings follow the following settings path: +
`Machine settings` => `Model settings` => `SID settings` => `SID model` => `USBSID-Pico` +
`Machine settings` => `Model settings` => `SID settings` => `Extra SIDs` => select the amount of extra SID's and set their addresses 

[%always]
<<<

==== vsid GTK
ALT+O or click Preferences/Settings to open the settings menu. +
*Sound configuration* +
The sound configuration will require tuning for the computer you use it on. +
In the screenshot below you can see that for this system I use the `pulse` audio driver and have the `Buffer size` set to 1 millisecond and `Fragment size` set to very small. +
These 3 settings can make or break the audio quality. +
image:images/software/vsid-soundsettings-linux-gtk.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/vsid-soundsettings-linux-gtk.png",width="600"] +
*SID configuration* +
For any audio to come out of the board you _need_ to select USBSID-Pico as SID engine. +
If you want to use more the one SID then you need to select the amount of `Extra SIDs` and set their I/O addresses. +
image:images/software/vsid-sidsettings-linux-gtk.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/vsid-sidsettings-linux-gtk.png",width="600"]

[%always]
<<<

==== vsid SDL2
Press F12 (Linux/Windows) / F10 (MacOs) to open the settings menu. +
*Sound configuration* +
The sound configuration will require tuning for the computer you use it on. +
In the screenshot below you can see that for this system I use the `pulse` audio driver and have the `Buffer size` set to 10 milliseconds and `Fragment size` set to very small. +
These 3 settings can make or break the audio quality. +
image:images/software/vsid-soundsettings-linux-sdl2.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/vsid-soundsettings-linux-sdl2.png",width="600"] +
To get to these settings follow the following settings path: +
`Sound settings` => `Output driver` => Select the driver you want to use +
`Sound settings` => `Buffer size` => Select the milliseconds you want to use +
`Sound settings` => `Fragment size` => Select the size you want to use +
*SID configuration* +
For any audio to come out of the board you _need_ to select USBSID-Pico as SID engine. +
If you want to use more the one SID then you need to select the amount of `Extra SIDs` and set their I/O addresses. +
image:images/software/vsid-sidsettings-linux-sdl2.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/vsid-sidsettings-linux-sdl2.png",width="600"]
To get to these settings follow the following settings path: +
`SID settings` => `SID model` => `USBSID-Pico` +
`SID settings` => `Extra SIDs` => select the amount of extra SID's and set their addresses +

[%always]
<<<

=== jsidplay2
This section covers the use of USBSID-Pico with `jsidplay2`

==== Settings
After starting JSidplay2 you can choose USBSID-Pico from the dropdown menu that says emulation and set the board to mono or stereo using the settings dropdown

image:images/software/jsidplay2-sid-config.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/jsidplay2-sid-config.png",width="600"]
image:images/software/jsidplay2-usbsid-config.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/jsidplay2-usbsid-config.png",width="600"]

==== c64jukebox
`c64jukebox` website that runs on `jsidplay2` available at https://haendel.ddns.net:8443/static/c64jukebox.vue

To enable USBSID-Pico in a WebUSB supporting browser (like Chrome) click on the `Hardware` tab and then click `Connect` in the USBSID-Pico box. After connecting search for any SID file in the search tab and click the play button.

WARNING: Because this play method is not perfected yet there will be delays when selecting a follow up tune and pressing stop or pause. This can be circumvented enabling `use await for USBSID write` on the Hardware tab, but this will severely impact playing tunes that rely on timing

image:images/software/c64jukebox-usbsid-config.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/c64jukebox-usbsid-config.png",width="600"]

[%always]
<<<

=== Denise
This section covers the use of USBSID-Pico with the C64 emulator of `Denise`

==== USBSID settings
Open the C64 settings menu and go to the audio tab. Under this tab on the left side you will see an `USBSID-Pico` option +
Here you can enable or disable the use of USBSID-Pico. If you have any audio issue you can try to increase the buffer and diff sizes.
image:images/software/denise-usbsid-config.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/denise-usbsid-config.png",width="600"]

==== SID settings
Open the C64 settings menu and go to the audio tab. Under this tab on the left side you will see a `Chip` option +
Here you can configure the amount of SID's you have on the board. Be sure to try the different settings for better output.
image:images/software/denise-sid-config.png[link="https://github.com/LouDnl/USBSID-Pico/blob/master/doc/images/software/denise-sid-config.png",width="600"]

[%always]
<<<

=== Retrodebugger
t.b.d.

=== sidplayfp
t.b.d.

== License
include::license-software.adoc[]

include::license-hardware.adoc[]

Author: {author} - generated on {revdate}
