================================================================================================================
PicoTuneWH - Version ptwh0v3a - G4EML PicoTuner - WinterHill Mode - Instructions v1
================================================================================================================


PicoTuneWH Software Versions
============================

2024-07-03	ptwh0v3a.uf2	DHCP improvements
2024-06-11	ptwh0v2n.uf2	set network host name
							remove 3 blinks after HI in morse
							detect incorrect Pico module and flash 'NO'
							add RESET, REBOOT, BOOTSEL, BIP, TSFLASH remote commands
							flash activity LEDs when attempting DHCP
2024-05-01	ptwh0v2c.uf2	reset the Ethernet chip at startup
							Pico green LED gives more DHCP info
							control second LNB psu
							output TS destination in port 9901 data
							re-instate board detection for MT or PT, for info only
2024-04-19	ptwh0v01y.uf2	minor mods
							created versions for W5100S-EVB-Pico and W5500-EVB-Pico
2024-04-13	ptwh0v01x.uf2	modified for multiple DHCP servers
2024-03-28	ptwh0v01w.uf2	remove board type detection - assume LEDs on GP0,1
							do not disable DVB-S when SR >= 250
							startup delay reduced to 3 seconds
							Pico LED and PicoTuner LEDs all flash during startup
2024-03-24	ptwh0v01v.uf2	auto detect board type
							added broadcast packet
							activity LEDs blink at startup
							checked compatibility with W5500 (after rebuild)
2024-02-26	ptwh0v01h.uf2	corrected off net IP detection
							LED blinks during 5 second startup delay
2024-02-25	ptwh0v01f.uf2	added incoming IP diagnostic
2024-02-24	ptwh0v01e.uf2	disable off net IP detection
2024-02-23	ptwh0v01d.uf2	First release


Overview
========

PicoTuneWH is software for the BATC PicoTuner board that emulates a single NIM WinterHill 
  and receives two signals at the same time, with commands and received data being sent over Ethernet.
There is no TS transfer by USB.
A USB connection is not required.
There are different .uf2 files for W5100S-EVB-Pico and W5500-EVB-Pico modules.
There is a debug facility over the USB serial port.
It may be possible to use this software with OpenTuner (0.B).
Network multicast is not supported.
A broadcast packet with device and receive info is transmitted every second on port 9997, 
  even if DHCP is unsuccessful.
See below for details on the broadcast packet.
If you do not have a WinterHill, see the BATC Wiki, particularly the Documentation and PC Software sections.


Finding the IP Address
======================

See the section on the broadcast packet below.


LNB PSU Output
==============

The LNB PSU is turned on by default at startup.
If you do not want LNB voltage, make sure the LNB PSU jumpers are not fitted on the PicoTuner board.
 

Software Loading
================

Connect the USB port to a PC.
Apply power to the PicoTuner while holding down the BOOTSEL button on the Pico board.
On a Pico with two buttons, this is the button nearer the USB socket.
The other button is RESET, which can be pressed while holding down the BOOSEL button.
A virtual disk drive window will open on the PC. Copy the appropriate .uf2 file to it. 
The PicoTuner will restart.


Quick Start
===========

In case of problems, or to find the PicoTunerWH IP address, see the section on the broadcast packet below.

If the software loaded is not the correct version for the type of Pico board,
the Pico and activity LEDs will repeatedly flash NO in morse (-.  ---)

Connect an Ethernet cable.
Load the W5100S or W5500 .uf2 file, depending on the type of Pico board.
The Pico and activity LEDs will flash HI in morse (....  ..)
There is a three second pause for initialisation.
The Pico then attempts to get an IP address via DHCP.
The Pico and PicoTuner activity LEDs do a single blink every second when waiting for a physical Ethernet link.
The LEDs do a double blink every second when waiting for a DHCP address.
The Pico LED is steady on when DHCP is successful.
If the LNB LO is 9750MHz and powered by the Mini/Pico/Tuner or otherwise, 
  the activity LEDs will start flashing after a few seconds, indicating double reception of the beacon.
The received transport stream (TS) data will not be sent anywhere, until a command is received.  


Required Equipment
==================

BATC PicoTuner board or BATC MK2 MiniTiouner with FT2232H replacement board.

WIZnet W5100S-EVB-Pico or W5500-EVB-Pico module. 

The Pico + WIZnet Ethernet hat combination should not be used because of voltage regulator issues
and the hat is too short to reach the end panel in the BATC PicoTuner.


Basic Operation
===============

Connect an Ethernet cable.
Load the W5100S or W5500 .uf2 file, depending on the type of Pico module.
At power up, the Pico and activity LEDs flash HI in morse as a confidence check.
It is possible to connect to the USB serial port to see debugging and receiver information - see below.
An IP address must be obtained by DHCP at startup. After this, the Ethernet cable can be unplugged and plugged.

Each receiver activity LED is steady on when no stations are being received, 
otherwise it flashes at a speed relative to the TS data rate.

This can be changed by sending a remote command - see below.

If the software loaded is not the correct version for the type of Pico module,
the Pico and activity LEDs will repeatedly flash NO in morse (-.  ---)


Parameters
==========

The maximum symbol rate of a single channel is about 10M.
The maximum network throughput is about 16M bits/s. 
Note that 10MS, FEC 3/4 gives 15M bits/s.
 
Network multicast mode is not possible.

The Base IP Port is 9900.
If you already have a WinterHill, the Base IP Port can be changed to 9904.
This provides receivers 5 and 6.
To do this, on a PicoTuner board, on the 10 pin GPIO header, 
  connect pin 8 counting from the right (GP28) marked 28, to pin 10 (GND) marked G.
Alternatively, put a jumper on Pico pins 33-34 (grounding GP28) and reboot. 
The Base IP Port can also be changed by sending a command over Ethernet.


QuickTune Setup and VLC reception
=================================

Send tuning commands to ports 9921 and 9922.
Receive transport streams on ports 9941 and 9942.
Info streams are available on ports 9901 and 9902 (duplicated on 9903 and 9904).
Add 4 to these port numbers if the base IP address has been changed by grounding GP28.
whpcviewer (on the BATC WinterHill Wiki) is a multi TS viewer for the WinterHill.
whpcrxcom (on the BATC WinterHill wiki) can be used to send receive commands.


Working with a WinterHill
=========================

If you already have a WinterHill, the PicoTunerWH can be set to emulate a second one.
Apply the jumper as descibed in the Parameters section above to make the PicoTunerWH receivers 5 and 6.
Add receivers 5 and 6 to the QuickTune configuration, with the PicoTunerWH IP address.

On whpcrxcom, CTRL-R will expand it to 8 receivers.
Set the second IP address for the PicoTunerWH.

Contact G4EWJ for a 16 screen version of whpcviewer.


QO-100 Frequency Self Calibration
=================================

After startup, the first receiver is set to the QO-100 beacon and does the calibration.
Two seconds later, the second receiver is set to the beacon.
If the LNB has an LO other than 9750MHz, put the beacon on receiver 1 manually. 


Ethernet MAC and Host Name
==========================

The WIZnet chip does not contain a MAC number (network hardware ID).

A MAC is formed at startup using the 3 byte WIZnet manufacturer prefix and 
the lower three bytes of the Pico serial number. 

	E.g. 28:CD:C1:41:97:2E

The lower three bytes of the Pico serial number are also used to form the host name.

	E.g. PicoTunerWH-41972E

The host name will be shown in 'attached devices' in the router. 


DHCP
====

The DHCP flow can be viewed by connecting to the USB serial port just after power up.
An IP address must be obtained at startup. After this, the Ethernet cable can be unplugged and plugged.
The Pico and activity LEDs do a single blink every second when waiting for a physical Ethernet link.
The Pico and activity LEDs do a double blink every second when waiting for a DHCP address.
The Pico LED is steady on when DHCP is successful.
The DHCP status is displayed over the USB serial port and in the broadcast packet.

If the Ethernet link is lost, the Pico and activity LEDs will display the DHCP status, as above.


USB Serial Port Connection
==========================

On a PC:
	using Device Manager, find the COM port that has been allocated 
	  and use Putty to make a serial connection at 9600 baud.

On an RPi:
	The USB serial port will be something like ttyACM0.
	There may be other ttyACM ports and the port allocated may not always be the same.

	To find the assigned USB serial port and Pico serial number:

		After the .uf2 file has been loaded, unplug and plug the PicoTuner USB cable.
		
		Type: 
		
			dmesg    
		
		to give a display similar to below.
		
		[ 5270.784596] usb 1-1.4: new full-speed USB device number 10 using xhci_hcd
		[ 5270.932417] usb 1-1.4: New USB device found, idVendor=2e8a, idProduct=000a, bcdDevice= 1.00
		[ 5270.932438] usb 1-1.4: New USB device strings: Mfr=1, Product=2, SerialNumber=3
		[ 5270.932457] usb 1-1.4: Product: Pico
		[ 5270.932474] usb 1-1.4: Manufacturer: Raspberry Pi
		[ 5270.932491] usb 1-1.4: SerialNumber: E660D4415741972E
		[ 5270.947997] cdc_acm 1-1.4:1.0: ttyACM0: USB ACM device

	Note the ttyACM allocation and the serial number.


Using the USB Serial Port on an RPi
===============================

Type:  

	stty -F /dev/ttyACM0 raw -echo & cat /dev/ttyACM0    or whichever tty port has been assigned.

You may need to retry when doing this after startup, if you try it too soon.
The Putty font size may need to be reduced to fit the data - try 11 point:

	Change Settings, Window, Appearance, Font Change


Giving the Pico a Fixed tty Name on an RPi
==========================================

The RPi will assign a ttyACM name to the Pico USB serial port, but it may not be the same every time.
The RPi can assign a fixed tty name to the Pico, based on the Pico's serial number.
This has to be done on every RPi that the Pico is plugged in to.	

Discover the Pico serial number as described in the USB Serial Port Connection section above.

Type:  

	sudo nano /etc/udev/rules.d/99-usbserial.rules

Enter a new line:  

	ACTION=="add",ENV{ID_BUS}=="usb",ENV{ID_SERIAL_SHORT}=="E660D4415741972E",SYMLINK+="ttyPT0"

Replace the serial number and tty name with your own.
Save and exit with CTRL-X then Y then ENTER.
Uplug and plug the Pico.

Type:  
	
	ls /dev 

to check that ttyPT0 appears. 

ttyPT0 will always be assigned to this particular Pico.
A potentially variable ttyACM port will also be assigned.

The command to connect to the USB serial port will now be:

	stty -F /dev/ttyPT0 raw -echo & cat /dev/ttyPT0
	
	
Getting Into Software Upload Mode
=================================

Instead of holding down the BOOTSEL button and connecting to USB to get into software 
upload mode, once this software has been loaded, the Pico can be put into software upload
mode again by opening a USB serial port connection at 1200 baud.

Note that this feature depends on the software already loaded on the Pico.
G4EML's PicoTuner USB software uses a different method.

On a PC, find the COM port number with Device Manager and open a serial connection
at 1200 baud with putty and then close it. The Pico virtual disk drive should now
appear and the .uf2 file can be dragged onto it.

On an RPi, find the ttyACM port that the Pico appears as and type:

	stty -F /dev/ttyACM0 1200 (use your own ttyACM port)

The Pico virtual disk drive will now be available.


Broadcast Packet on Port 9997
=============================

This is sent every second, even if an IP address cannot be obtained.

 =======================================
        PicoTuner Broadcast
 ---------------------------------------
        Sequence   105
        Run time   112s
  Broadcast port   9997
     Pico serial   E6623C3767182B31
    Net hardware   WIZnet W5500
             MAC   28:CD:C1:18:2B:31
       Host name   PicoTunerWH-182B31
      DHCP state   Success
 Lease remaining   3495s
      IP address   192.168.77.163
        NIM type   FTS4334L
    LNB supply X   hi
    LNB supply Y   absent
        Software   ptwh0v3a-w5500.uf2
            Mode   WinterHill
    Base IP port   9900
             RX1   10496.708 PE1FWC
             RX2   10498.220 F5DB
   TS target RX1   192.168.77.247:9941
   TS target RX2   192.168.77.247:9942
 =======================================

To display this on an RPi, type:  

	netcat -kluvw 0 9997
	
Windows does not seem to have an inbuilt equivalent of netcat, 
but there are probably utilities that can be installed. 	
	
	
Remote Commands via Ethernet
============================

Remote commands may be sent to port 9920, when the Base IP Port is 99xx.
If the Base IP Port is, for example, 8804, commands should be sent to port 8820.

	Reset:						[to@wh] reset=147		clear any remote settings and reboot
	Reboot:						[to@wh] reboot=258		reboot, but do not clear any remote settings
	BOOTSEL:					[to@wh] bootsel=369		go into software upload mode
	Change the Base IP Port:	[to@wh] bip=9908		change the Base IP Port and reboot
	Change activity LED action:	[to@wh] tsflash=0		activity LEDs are steady on when receiving, otherwise off

To do this from an RPi, type for example:  

	echo "[to@wh] bip=9908" | netcat -uw1 192.168.77.204 9920		using the IP address of your PicoTunerWH
	
	                        | is the vertical bar character
	
Windows does not seem to have an inbuilt equivalent of netcat, 
but there are probably utilities that can be installed. 	
		
Valid Base IP Port settings are any even number from x00 to x14, where xx is 11 to 654.
The Base IP Port and TSFLASH values that are set by remote commands, are forgotten when power is removed.

	
=============================================================================================================================
g4ewj@yahoo.com
2024-07-03

