====== NinoTNC udev Guide ======
This guide is intended to assist you in creating static devices for any number of NinoTNCs connected your Raspberry Pi. The device nodes set up will remain constant across restarts, power cycles, and moving the NinoTNC usb cable to a different usb port.
This wiki article is **NOT** to be used as an exact key-for-key and click-for-click guide, and also assumes that you are comfortable using the command line. If you are not using a Pi, the steps should also applicable to any Debian/Ubuntu derived system.
----
===== Software Prerequisites =====
A few specific pieces of software are required for configuring the USB chip used on the NinoTNC so that each individual unit can be identified by a serial number, instead of the USB socket that it is plugged into.
* The ability to act and edit files as the system superuser (root)
* A working git installation
* MPC2221a USB chip setting adjustment tool
First, ensure you have a working git installation with the command ''sudo apt install git''
After git is installed/updated, get a copy of the MPC2221a settings utility using ''cd ~ && git clone https://github.com/g5dsg/2221aTool.git''
The settings tool is written in the python language, and it needs a couple of extra support packages to be able to work. To install the ''click'' and ''pyusb'' packages: ''sudo apt install python3-click python3-usb''
----
==== Set the Serial Number ====
//**Before proceeding with any steps in this section, you should only have one NinoTNC connected. This ensures that the changes are made on the correct device.**//
First, enable the serial number reporting with ''sudo ~/2221aTool/2221aTool.py enum-serial 1''
The chips have a pre-set serial number already configured, but you can change it if you wish. Use the command ''sudo python3 ./2221aTool.py set-serial'' followed by your desired serial number, which can be up to 30 unicode characters.
//Example:// ''sudo python3 ./2221aTool.py set-serial 0123456789''
When you are finished enter the command ''sudo dmesg -W'' then remove and reconnect your NinoTNC. The new serial number will be displayed as part of the device information. Use CRTL + c to return to your prompt.
----
==== Set the Product Info ====
//**Before proceeding with any steps in this section, you should only have one NinoTNC connected. This ensures that the changes are made on the correct device.**//
You can change the reported product description to better identify the device, and the process is very similar. Use ''sudo python3 ./2221aTool.py set-description'' followed by your desired description, which can be up to 30 unicode characters.
//Example:// ''sudo python3 ./2221aTool.py set-description NinoTNC-GB7BMY-HF''
When you are finished enter the command ''sudo dmesg -W'' then remove and reconnect your NinoTNC. The new description will be displayed as part of the device information. Use CRTL + c to return to your prompt.
----
==== Create the udev Rules ====
You will need to create or amend the file ''/etc/udev/rules.d/99-ninotnc.rules'' using the serial numbers you have chosen, or located using the ''dmesg -W'' command.
=== Devices named by hand ===
This example will make named links for each device based on their serial numbers, allowing the function to be visible\\
Example udev rules for 2 TNCs with serials ''0123456789'' and ''987654321'':
# Create descriptive links to make refering to NinoTNC's easier
SUBSYSTEM=="tty", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="00dd", ATTRS{serial}=="0123456789", SYMLINK+="NinoTNC-2m"
SUBSYSTEM=="tty", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="00dd", ATTRS{serial}=="9876543210", SYMLINK+="NinoTNC-4m"
=== Serial number names ===
This example will create a link for each NinoTNC using it's serial number as the device name in ''/dev'', but requires you to remember which NinoTNC serial is used for each purpose
# Create descriptive links to make refering to NinoTNC's easier
SUBSYSTEM=="tty", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="00dd", SYMLINK+="NinoTNC-%s{serial}"
jonathan@GB7BMY /dev> ls -lah tnc-*
lrwxrwxrwx 1 root root 7 Aug 20 13:23 0003794435 -> ttyACM0
lrwxrwxrwx 1 root root 7 Aug 20 13:23 0004013920 -> ttyACM1
----
=== Product Description names ===
This example shows that if you have set the Product Description for easier identification of a NinoTNC, it can also be used to create the name links in ''/dev''
SUBSYSTEM=="tty", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="00dd", ATTRS{product}=="NinoTNC-GB7BMY-VHF-2m", SYMLINK+="NinoTNC-VHF-2M"
SUBSYSTEM=="tty", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="00dd", ATTRS{product}=="NinoTNC-GB7BMY-HF", SYMLINK+="NinoTNC-HF-40M"
jonathan@GB7BMY /dev> ls -lah NinoTNC-*
lrwxrwxrwx 1 root root 7 Aug 20 13:23 NinoTNC-VHF-2M -> ttyACM0
lrwxrwxrwx 1 root root 7 Aug 20 13:23 NinoTNC-HF-40M -> ttyACM1
This format could also be used in place of the two lines above, and would create the devices in ''/dev'' named with the exact product description. It is not recommended to have spaces in the product description if you use this method.
SUBSYSTEM=="tty", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="00dd", SYMLINK+="%s{product}"
jonathan@GB7BMY /dev> ls -lah NinoTNC-*
lrwxrwxrwx 1 root root 7 Aug 20 13:23 NinoTNC-GB7BMY-VHF-2m -> ttyACM0
lrwxrwxrwx 1 root root 7 Aug 20 13:23 NinoTNC-GB7BMY-HF -> ttyACM1
==== Final Steps ====
To activate the newly-created rules you can either remove and reconnect the NinoTNC USB cable, or use the command ''sudo udevadm trigger''. Once either has been carried out, the new devices will be visible in ''/dev'' for use in your application.