#==================================================================
# A python example of receiving data over RS232 and using it to update Vmix using HTTP
# I hope this example is a good start for you create your own code.
#
# If you find any bugs or errors please feed them back so I can correct,
# I'm not a long time python programmer and am much more at home with low
# level C on a micro-controller, so many have occasionally done things in a
# non-pythonic way.
#
# This python example code is intended to be used with the accompanying vmix
# project which includes a title with items with the correct names

# The code is split in to 4 main parts:
#
# 1) The main() loop that calls the other parts.
#    All the functions called by the main loop are fall through (non-blocking) so
#    main() loops continuously, this is intentional so other things can be done here.
#    There is a short sleep() in the main loop to reduce CPU load.
#
# 2) serialreader() that takes chars from the serial port, looks for start 
#    and end of message bytes and builds up the incoming message. When a full
#    message is received it is passed back to the main loop. 
#    This function is fall through, in a larger project it would probably be better
#    to use asyncio or a thread here, but the aim of this example is to keep it simple.
#    This function could be modified to handle different protocols and do additional
#    checks like verifying message checksums if present.
#
# 3) decodemessage() that tries to decode the received message and depending on the
#    contents do things to update vmix. You could modify this for any protocol you
#    are using, and what you want to with the data received.
#
# 4) A group of functions to update Vmix. send_vmix_command() actually sends the
#    update to Vmix and the other functions like update_vmix_text() generate the
#    specific commands to send. I normally add a new update_vmix_xxxx() function
#    each time I use a new function in the list here:
#    https://www.vmix.com/help26/ShortcutFunctionReference.html
#
# For this example lets invent a simple protocol to send commands over serial:
#    All commands start with a '*' and end with a '!'.
#       Note. Many protocols end in a LF or CR char but I have deliberately chosen
#       not to here, to demonstrate 'Start' and 'End' of message markers.
#    Parts/fields of the command are separated by comma.
#    The first field is the command.
#    Remaining fields are dependent on the command.
#    Text values are in contained in "" to allow commas in text.
# Eg *command,field2,field3,"This is, field4"!
#
# This simple protocol has the obvious flaw that you can't include  * or !
# in the fields, but it will do for this example code. Often the protocols
# I decode use 'unprintable' values as start & end of message markers eg: b'\x01
# (SOH) and b'\x04 (EOT). But here for ease of demonstration I wanted the 
# protocol and commands to be possible to type in a terminal.
#
# And now lets invent some commands to use over this protocol:
#
# *NA,"England"!        NA: Set the name of Team A to the value in field 2
# *NB,"Scotland"!       NB: Set the name of Team B to the value in field 2
# *SA,1!                SA: set the score of team A to the value in field 2
# *SB,2!                SB: set the score of team B to the value in field 2
# *OE,1,1!              OE: enable/disable the score overlay, field2: 0=disable, 
#                           1=enable overlay, field3: the Vmix overlay number
# *OE,0,1!                  example of turning off overlay 1
# HINT:, try the exact commands above on the supplied vmix project
#
# You will need to set the serial port and vmix ip address below.
#
# I have left commented out debug print() calls that you can re-enable
# if you desire to see what is going on at various points.
#
# This code has been tested on Windows, I'll try it on Linux soon and update
# these instructions.
#
# V1.0 MCL 31/3/2023
#   - initial release
# 
#==================================================================