---

Fig 1. 

 

Introduction
ObsComm is a new Communication System for the Observatory based on the UDP protocol..

The need for a communication system for adhoc and custom communication across the observatory and house computers has been recognised for some time. This will operate in addition to existing IP/TCP communication of specific record between computers. 

Based on discussions with Copilot  the UDP protocol has been selected for the communication system, following which code was developed again with CoPilot to put into a shared UpbComms.vb file/module with class definitions for UdpBroadcaster, UdpListener, UdpNode and UdpMessage.  UdpNode is a node that comprises both a listener and a broadcaster to hide the underlying mechanism and allow programs to work with a single object reference (ObsComm).

AstroMain is the first program setup to use the new UDP system, but other programs in the AstroSuite will be set up in due course.

The basic setup is as follow.  One new declaration is placed in the program's globals.vb or general.vb module :
   Public ObsComm As UdpNode   
ObsComms is then set up from the program's Load() routine :
   ObsComm = New UdpNode(5000, "AstroMain")
   AddHandler ObsComm.MessageReceived, AddressOf HandleObsCommMessage
   ObsComm.StartListening()
Messages are broadcast to the network from anywhere in the program using code like :
     ObsComm.SendMessage("Hello World")

A routine 'HandleObsCommMessage()'  is added to the program to handle received messages.  The contents of the handler will be different in each program according to the communication plan which is still being developed.
   Public Sub HandleObsCommMessage(msg As UdpMessage)
   End Sub

UdpMessage currently has 6 string fields
   RemoteAddress,  senderComputer, senderApp, TimeStamp, MessageType, Message/Payload

Implemented in AstroCommon and AstroMain 3.79.13 on 2025-01-04

AstroMain's 'HandleObsCommMessage()'  routine is placed within the Manager module, but outside of the ObsManager class object

Analysis

The precise message types & payloads to be used need to developed and the requirements of program specific handlers need to be defined.
 - What is UDP used for in the observatory ?
 - What fields should every message contain ?
 - What message types do I need ?
 - What does each app broadcast ?
 - What does each app listen for ?
 - What timestamp format ?
 - What payload format ?
 - Is a UdpMessage class required?
 - Is protocol versioning required ?

What is UDP used for in the observatory ?
UDP is intended to provide general and custom communication between the different AstroSuite programs and computers running within the Observatory/House Network.
  - The new system will eventually replace the existing use of flag files and the like
  - The new system will not replace the existing use of regular TCP/IP communication of data records (ObsEnv, CloudSensor.WeatherData)
  - Optionally the new UDP system might replace the existing ObsCamControl (TCP/IP) system.


Current Flag File messages:
 Broadcast Functions:

 AstroMain Disconnect AstroGuard Services()- SU.BaseFolder\Disconnect.dat         AstroGuard
 AstroMain ConnectAstroGuardServices()     - SU.BaseFolder\Connect.dat            AstroGuard
 AstroMain WriteRestartDomeFlag()          - SU.BaseFolder\RestartDome.dat        AstroGuard
 AstroMain RestartTheSky6()                - SU.BaseFolder\RestartTheSkyFlag.dat  AstroPlan
 AstroMain RestartTheSky6()                - SU.BaseFolder\RestartTheSkyFlag.dat  AstroVOE
 AstroMain SetFlagChanged("Session")       - Flag_SessionChanged.dat              AstroPlan
 AstroMain SetFlagChanged("Plan")          - Flag_PlanChanged.dat                 AstroPlan
 AstroMain SetFlagChanged("Event")         - Flag_EventChanged.dat                AstroPlan
 AstroMain SetFlagChanged("Alert")         - Flag_AlertChanged.dat                AstroPlan
 AstroMain SetFlagChanged("NewSession")    - Flag_NewSessionChanged.dat           AstroPlan
 AstroMain SetFlagChanged("ResumeSession") - Flag_ResumeSessionChanged.dat        AstroPlan
 AstroMain SetFlagChanged("EndSession")    - Flag_EndSessionChanged.dat           AstroPlan
 AstroMain OpenTargetInAstroPlan(TargetID) - CCD Imaging\Common\OpenTarget.dat    AstroPlan
 AstroSN   OpenTargetInAstroPlan(TargetID) - CCD Imaging\Common\OpenTarget.dat    AstroPlan

 AstroMain ObsManager.InitiateNewPlan      - SU.BaseFolder \CreatePlanFlag.dat    AstroPlan

 Listening Functions
 AstroMain RemoteAbortListener()           - CCD Imaging\AbortAstroMainJob.dat      from ?
 AstroMain RemoteAbortListener()           - CCD Imaging\KillAstroMainJob.dat       from ?
 AstroMain ObsManager.MainLoop, WaitforNewPlan - SU.BaseFolder \CreatePlanFlag.dat  from AstroPlan
 AstroMain CheckForNewToO()                - SU.BaseFolder \ToO_File.dat"           from AstroPlan/AstroVOE

 AstroPlan WsFileWatcher.Start             - CCD Imaging\CreatePlanFlag.dat         from AstroMain
 AstroPlan WsFileWatcher2.Start            - CCD Imaging\RestartTheSkyFlag.dat      from AstroMain
 AstroPlan FlagChanged("Session")          - Flag_SessionChanged.dat
 AstroPlan FlagChanged("Plan")             - Flag_PlanChanged.dat                 AstroMain
 AstroPlan FlagChanged("Event")            - Flag_EventChanged.dat                AstroMain
 AstroPlan FlagChanged("Alert")            - Flag_AlertChanged.dat                AstroMain
 AstroPlan FlagChanged("NewSession")       - Flag_NewSessionChanged.dat           AstroMain
 AstroPlan FlagChanged("ResumeSession")    - Flag_ResumeSessionChanged.dat        AstroMain
 AstroPlan FlagChanged("EndSession")       - Flag_EndSessionChanged.dat           AstroMain
 AstroPlan RemoteTargetOpener()            - CCD Imaging\Common\OpenTarget.dat"   AstroMain
One thing that is commonly used in flag files is that the deletion of flag file is used as indicator that request has been carried out and/or heard

What fields should every message contain ?
  - IP of the computer sending the message           (senderIP as string)
  - Name of the Computer sending the message   (senderComputer as string)
  - Name of the Application sending the message (senderApp as string)
  - TimeStamp for the time that message sent       (senderTimeStamp as string)
  - The message's MessageType.                           (messageType)
  - The message or payload                                     (message)

  - Name of the Audiance Computer  ?                   (forComputer as string)    (default *)
  - Name of the Audiance App ?                              (forApp as string)              (default *)

 The Listener will also add
  -  TimeStamp for the the time that message was received   (receivedTimeStamp)

Update 2026-01-05
- AstroMain - AstroPlan Notification Event communications added (replacing FlagFiles)
- AstroMain - AstroGuard Command/Completions Events added: ConnectServices/DisconnectServices (replacing FlagFiles)
- AstroMain - AstroObsCam Action Events added (replacing TCP/IP comms)
- AstroMain - AstroPlan OpenTarget Events added: (replacing FlagFiles)
- AstroSN - AstroPlan OpenTarget Events added: (replacing FlagFiles)

 

ObsComm Protocol v2 - Specification  (2026-01-06)

A lightweight, structured UDP messaging protocol for inter‑application communication across the observatory ecosystem.

1. Purpose

ObsComm v2 defines a consistent, deterministic message format for communication between astronomy applications running on one or more computers. It supports:

• Directed commands
• Directed responses
• Region scoped broadcasts
• LAN wide broadcasts
• Cross region targeted operations
• Multi machine, multi-application environments

The protocol is intentionally simple, human readable, and easy to extend.

2. Message Structure

Every ObsComm v2 message contains the following fields:

• TimeStamp - UTC Timestamp
• SenderComputer - Machine Name of the sender
• SenderApp - Name of the sending application
• TargetRegion - Intended receiving region,  "Obseratory", "Development" or * for LAN-Wide
• TargetComputer - Intended receiving computer or * for broadcast
• TargetApp - Intended receiving application or * for broadcast
• MessageType - Category of message  "Command""Response""Event""Error"
• Action
• Value

All fields are required.

3. MessageType Semantics

3.1 Command
A request for another application to perform an action.

• Action = operation name
• Value = parameters (may be empty)

Must be directed (TargetApp and/or TargetComputer not "*") unless intentionally broadcast

3.2 Response
A reply to a command.

• Action = same as the originating command
• Value = "Completed", "Failed", "Progress:xx", or other status text

3.3 Event
A broadcast notification. ' broadcast state change'

• Action = event name
• Value = event data

Typically uses TargetApp="*" and TargetComputer="*"

3.4 Error

Indicates a failure condition - "something went wrong"

•  Action = operation that failed
• Value = error description

3.5 Other types

• Alert - warning requiring attention
• Log - information or diagnostic text
• Query - request for Information
• Reply - response to a query
• Discovery - Auto-discovery of apps
• Handshake  - Initial connection / protocol negiotation

4. Region Rules

5. Routing Logic (Receiver‑Side)

6. Examples

7. Versioning

Include a version field in the message header if you anticipate future changes:
   ProtocolVersion = "2.0"

Receivers should ignore messages with unsupported versions.

8. Design Principles

ObsComm v2 is built on:

• Explicitness — no hidden assumptions
• Determinism — predictable routing
•  Isolation — development vs observatory separation
•  Extensibility — new actions and message types can be added without breaking existing code
• Simplicity — easy to read, debug, and maintain

1.0 Introduction

AstroMain Observatory Control Progam has evolved over many years, growing into a sophisticated application that supports live imaging, monitoring, analysis, and scientific workflows. Much of the original code was developed incrementally in response to real-world operational needs. While this approach delivered a powerful system, it also created areas where responsibilities blurred, sequencing became fragile, and behaviour became difficult to reason about.

This refactoring project aims to bring clarity, structure, and long-term maintainability to the system in the area of Create/Reopen Sessions without compromising operational stability. The goal is not to rewrite everything, but to map the existing behaviour, extract responsibilities, and introduce a clean, layered architecture that future-proofs the application.

These notes document the design thinking, implementation steps, and technical details behind the refactor.  Review showed that there was a clear division of programe operation into Active Mode and Passive Mode.

• Active Mode

  Active Mode is the Observatory's live operational mode, where the system controls real hardware and performs real-time imaging. In this mode, AstroMain manages the telescope, cameras, focuser, rotator, power systems, monitoring services, and environmental checks. It prepares the full observatory environment, coordinates CCDSoft, starts monitoring threads, and updates the UI with live telemetry. Active Mode is used for Live, General, and Test observing sessions where real equipment is active and images are being acquired
   

• Passive Mode

  Passive Mode is the Observatory's analysis and review mode, used when no hardware is active. It loads an existing session's data, charts, logs, and images for offline inspection. Passive Mode supports Reduced, Analysis, and VMA workflows, allowing the user to review results, analyse image sets, inspect charts, and work with session data without interacting with observatory hardware. Passive Mode is entirely file-driven and safe to run at any time, even when the observatory is offline.

This refactoring effort is about more than cleaner code. It is about building a robust, maintainable foundation for the Observatory's automation system. By mapping legacy behaviour, clarifying responsibilities, and introducing a structured pipeline for both Active and Passive Modes, the system becomes easier to understand, safer to modify, and more resilient in real-world operation.

---

2.0 Design Overview

2.1 Goals

• Preserve all existing behaviour and operational stability
• Make the Active and Passive pipelines explicit, traceable, and maintainable
• Separate responsibilities into clear phases
• Improve naming, readability, and intent-expression
• Reduce duplication and legacy artefacts
• Support safe incremental migration
• Maintain detailed logging for real-world diagnostics

2.2 Architectural Principles

• Layered Responsibility

  Each layer has a clear role:
  
  • Caller Layer - expresses intent
  • Controller Layer - orchestrates the lifecycle
  • Activation Pipeline - performs mechanical steps
  • Runtime Layer - brings the environment online
  • UI Layer - reflects state, not drive it
     

• Dual-Path Migration

  New routines run alongside legacy ones until behaviour is validated.
   

• Traceability

  Logging remains inline to preserve the exact execution timeline.
   

• Non-Disruptive Refactoring

  Changes are incremental, reversible, and grounded in real code.

---

3.0 Active Mode Pipeline

Pipeline

3.1 Pipeline Diagram

┌──────────────────────────────┐   ┌──────────────┐
│ btnLiveSession.Click         │   │              │
│ btnGeneralSession.Click      │   │  ObsManager  │         
│ btnTestSession.Click         │   │              │ 
│ comboSessionList.Changed     │   └───┬──────────┘
│ btnSelectSessionFolder.Click │       │
└──────────────┬───────────────┘       │
               │                       │
┌──────────────▼───────────────┐       │
│ RequestActiveSessionFromUI() │       │
└──────────────┬───────────────┘       │
               │                       │
┌──────────────▼───────────────────────▼─────┐    
│ RequestActiveSession()                     │ 
│ - Phase 1. CreateActiveSessionIdentity()   │     
│ - Phase 2. ValidateActiveSessionIdentity() │
│ - Phase 3. Close Previous Session          │
│ - Phase 4. ActivateActiveSession()         │   
└──────────────┬─────────────────────────────┘
               │
┌──────────────▼─────────────────────────────┐
│ ActivateActiveSession()                    │     
│ - Phase 5  CreateSessionInDatabase()       │    
│ - Phase 6. StartActiveSessionPreparation() │    
│ - Phase 7. SetupSessionFoldersAndFiles()   │   
│ - Phase 7. BeginActiveSessionFiles()       │    
│ - Phase 8. PrepareUIForActiveSession()     │    
└──────────────┬─────────────────────────────┘
┌──────────────▼─────────────────────────────┐
│ Threaded Operation                         │     
│ - Phase 10. InitialiseActiveSessionState() │    
│ - Phase 11. BeginActiveSessionFiles()      │
│ - Set Completion Flag                      │
└─────────┬───────────────────────┬──────────┘  
          │                       │
┌─────────▼───────────┐    ┌──────▼───────┐  
│ Manual Operatitions │    │  ObsManager  │
└─────────────────────┘    └──────────────┘ 

3.2  Active Pipeline Phases

Phase 1 - Session Identity Creation

Handled by CreateActiveSessionIdentity()

• Determine session type
• Determine night date
• Determine session ID
• Determine session name
• Determine new/resumed state
• Create ActiveSessionIdentity

Phase 2 - Validation

Handled by ValidateActiveSessionIdentity().  Helped by ConfirmNewSession() & ValidateProposedSession()

• Validate session type
• Validate night date
• Validate environment
• Allow cancellation

Phase 3 - Session Closing

• Close existing session if required
• Ensure clean transition

Phase 4 - Activation Pipeline Entry

Pass identity into ActivateActiveSession(identity).

Phase 5 - Insert Session in Database

Handled by CreateSessionInDatabase(identity)

Phase 6 - StartActiveSessionPreparation

StartActiveSessionPreparation(identity)

Phase 7 - Setup Storage

Handled by SetupSessionFoldersAndFiles().

• Create session folders
• Open log and report files

Phase 8 - Begin Active Session File

Handled by BeginActiveSessionFile().

• Record Session Creation/Resumption in LogFile
• Record Session Creation/Resumption in ReportFile
• Record Session Creation/Resumption in Database
• Open Observatory Reports

Phase 9 - Setup UI for Session

Handled by objConsole.PrepareUIForActiveSession()

• Add Observatory Tabs
• Update Session Fields

Phase 10 - State Initialisation

Handled by InitialiseActiveSessionState(), as threaded operation.

• Reset timestamps
• Reset counters
• Initialise charts
• Initialise session data
• Initialise VM fields
• Prepare UI state
• Load ToO lists
• Initialise focus profiles
• Initialise session images

Phase 11 - Runtime Initialisation

Handled by InitialiseActiveSessionRuntime(), as threaded operation.

• CCDSoft AutoSave number
• Windows reboot checks
• Program version reporting
• COM port and Zigbee reporting
• Start monitoring
• Switch to Observatory tab

---

4.0 Passive Mode Pipeline

4.1 Passive Pipeline Diagram

┌────────────────────────────────┐     
│  btnSelectLastSession.Click    │      
│  btnSelectPriorSession2.Click  │               
│  btnSelectPriorSession3.Click  │      
└──────────────┬─────────────────┘      
               │                      
┌──────────────▼───────────────┐
│ SelectPassiveSessionFromUI() │
└──────────────┬───────────────┘
               │
┌──────────────▼────────────────────────┐
│ SelectPassiveSession()                │
│  Phase 1. ValidatePassiveSession()    │
│  Phase 2. CloseAllFiles()             │
│  Phase 3. SetupPassiveSession()       │
│  Phase 4. OpenPassiveSessionFiles()   │
│  Phase 5. PrepareUIForPassiveSession()│
└──────────────┬────────────────────────┘
               │
┌──────────────▼─────────┐
│ Manual Operatitions    │
└────────────────────────┘

4.2 Passive Pipeline Phases

 Phase 1 - Session Identity Creation

• Determine Passive Mode type
• Determine session ID
• Determine session name
• Determine night date
• Determine new/resumed state
• Create PassiveSessionIdentity

Phase 2 - Validation

• Ensure session exists
• Ensure required files and folders exist
• Ensure Passive Mode type matches session
• Ensure no Active Mode session is running

Phase 3 - Storage Setup

• Create Passive session folders
• Open Passive session files
• Open Reduced, VMA, or Analysis files
• Open log and report files

Phase 4 - State Initialisation

• Reset timestamps
• Reset counters
• Load existing Passive session data
• Initialise charts
• Initialise VM fields
• Prepare UI state
• Load ToO lists if relevant

Phase 5 - Runtime Initialisation

• Load analysis tools
• Load Reduced or VMA datasets
• Prepare charting environment
• Populate grids, lists, and graphs

Phase 6 - UI Transition

• Switch to Passive Mode tab
• Populate UI fields
• Display session metadata
• Display charts and analysis tools

---

5.0 New Code Components (Types and Routines)

5.1 New Modules

• SessionController

5.2  New Classes

• ActiveSessionIdentity
  • SessionType
  •  SessionTypeStr
  •  NightDate
  •  SessionID
  •  SessionName
  • IsNewSession
  • IsLiveSession
  • IsCancelled

5.3 New Enums

• ConsoleMode
  -  Observatory, Solar, Reduction, Analysis, Vma, None
• SessionType
  - Live, General, Test, Undefined

5.4 New Routines - Active Mode

• RequestActiveSession(SessionType)
• CreateActiveSessionIdentity()
• ValidateActiveSessionIdentity()
    - ConfirmNewSession(identity)
    - ValidateProposedSession(identity)
• ActivateActiveSession(Identity)
• SetupSessionFoldersAndFiles()
• InitialiseActiveSessionState()
• InitialiseActiveSessionRuntime()
    - ReportLastDatabaseTransfer()
    - ResumeSessionCharts()
    - SetupCCDSoftForActiveSession()

5.4 New Routines - Passive Mode

• SelectPassiveSessionFromUI
  RequestPassiveSession(mode, sessionID)
• HandlePassiveSessionRequest()
• ActivatePassiveSession(identity)
• SetupPassiveSessionStorage()
• InitialisePassiveSessionState()
• InitialisePassiveSessionRuntime()

5.5 New Routines - Helpers

• GetConsoleModeName()
• IsActiveSessionMode()

---

6.0 Replaced Code Components

As part of the refactoring of the Create/Reopen Session pipeline, several legacy routines have been replaced, consolidated, or re-scoped. The goal was not to change behaviour, but to reorganise responsibilities into clearer, more maintainable units. This section documents the routines that have been superseded, the new routines that replace them, and the reasoning behind each change.

Routines Replaced by New Pipeline Process

• globals.AssignObservatorySession()
• ObsConsole.OpenSession()
• ObsConsole.ContinueSession()
• ObsConsole.RunOpenSession() ?
• ObsConsole.OpenSessionByThread()
  
• StartActiveSession()
• OpenSession()
• OpenNewSession()
• OpenExistingSession()
• OpenSessionFiles()
• SetupSession()
• InitialiseSession()
  

Routines Modified by New Pipeline Process Routines

• AssignGeneralObservatorySession()   - no longer references  AssignObservatorySession()
• ObsManager.SetupSession() - no longer references  AssignObservatorySession()
• ObsManager.ProgressSessionDate() - no longer references  AssignObservatorySession()
  
• ObsConsole.AutoCreateSession() - no longer references ObsConsole.OpenSession()
• SessionController.RequestActiveSessionFromUI() - no longer references ObsConsole.OpenSessionByThread()

Remove Temporarily Employed Flags

• bUseNewActiveSessionPath

---

7.0 Technical Details

Identity Objects

Identity objects use Properties instead of fields to support validation, logging hooks, immutability control, binding, and future evolution.

Logging and Reporting

Logging remains inline to preserve exact execution order, real-world diagnostics, timing analysis, and hardware interaction traces.

UI Orchestration

• IgnoreAtStartUp prevents spurious event firing
• Dummy focus targets prevent unwanted TextBox focus
• UI transitions occur only after runtime is ready

---

8.0 Future Work

• Further extraction from Phase 6
• Relocation of session lifecycle events
• Consolidation of reporting routines
• Additional naming refinements
• Passive Mode refactor using the same incremental approach