RS232 API Documentation

Overview

The FLC system provides an RS232/UART interface for remote control and monitoring. This API allows external systems to execute routines, control hardware, and monitor the status of the laser system.

The RS232 API documentation provides detailed information on:

  • Direct hardware control commands

  • Routine execution commands organized by section (DEFAULT, NLOS, etc.)

  • Parameters and return values for each command

  • Example commands and sequences

  • Links to related routine diagrams

  • Troubleshooting information

Alternative Formats

If you prefer a different format, you can also download the documentation as a standalone HTML page or a Markdown file.

RS232 API Documentation

RS232 API Documentation

Overview

The FLC system provides an RS232/UART interface for remote control and monitoring. This API allows external systems to execute routines, control hardware, and monitor the status of the laser system.

Available Sections

routines NLOS

Connection Parameters

To connect to the RS232 API, use the following parameters:

  • Baud Rate: 115200
  • Data Bits: 8
  • Parity: None
  • Stop Bits: 1
  • Flow Control: None

Command Format

All commands follow a simple text-based format:

command [parameter1] [parameter2] ...

For example:

write_digital ONHV 0 true

Response Format

Responses are returned as strings and can be one of the following formats:

  • Success: OK or a specific success message
  • Error: ERROR: <error message>
  • Return value: True <data> or False <error message>

Command Categories

The RS232 API commands are divided into two main categories:

  1. Direct Hardware Control: Commands that directly control hardware functions like digital/analog I/O
  2. Routine Execution: Commands that execute pre-defined routines

Parameter Handling

When executing routines that require parameters, values should be provided in the correct order and format:

  • String values: Provided as is (e.g., "value")
  • Numeric values: Provided without quotes (e.g., 123, 45.67)
  • Boolean values: Provided as true or false (lowercase)

For example, if a routine requires a wavelength parameter:

run_set_wavelength 1064.5

Error Handling

If a command fails during execution, an error message will be returned with the following format:

ERROR: <error message>

Common errors include:

  • Invalid command format
  • Invalid parameters
  • Hardware access failures
  • Safety interlock triggers
  • Component status errors

RS232 API Documentation - routines

Back to Index

Overview

This document describes the RS232 API commands available for the routines subsystem.

Direct Hardware Control Commands

Interface Control

write_digital

Callback function for the digital output buttons (ToggleButtons).

Format: write_digital <name> <portnum> <state>

Parameters: - name: string - portnum: integer - state: boolean value ("true"/"false" or "1"/"0")

Example: write_digital ONHV 0 true

Returns: Success/error status and the written value

Description: This command directly controls the digital outputs of the control board. It's used to toggle hardware components on and off, such as power supplies, high voltage sources, and pulse generators.

write_analog

Callback function for the analog output buttons (DACGroup).

Format: write_analog <name> <portnum> <value>

Parameters: - name: string - portnum: integer - value: float

Example: write_analog DAC1 2 3.5

Returns: Success/error status and the written value

Description: This command controls analog outputs, allowing precise control of voltage levels for components such as DACs (Digital-to-Analog Converters). It's used for controlling variable parameters like power levels and timing signals.

Adc Control

adc_single_offload

Perform single offload Example command: 'GET adc_single_offload'

Format: adc_single_offload

Example: adc_single_offload

Returns: ADC data or success message

Description: This command reads the current ADC data from BRAM (Block RAM) registers and returns the values. It's useful for checking analog signal values at a specific moment in time.

adc_continuous_offload

Perform single offload Example command: 'GET adc_single_offload'

Format: adc_continuous_offload <state>

Parameters: - state: boolean value ("true"/"false" or "1"/"0")

Example: adc_continuous_offload true

Returns: ADC data or success message

Description: This command controls the continuous reading of ADC data. When enabled, the system will continuously read and transmit ADC values until disabled. This is useful for monitoring analog signals over time.

Available Routines for routines

The following routines are registered in the routines subsystem and can be executed via RS232:

run_measure_and_check_signals

Check Signals

View Sequence Diagram

Format: run_measure_and_check_signals <frequency>

Example: run_measure_and_check_signals "example_string"

Description:

Steps:

  • do_offload: single_offload(plot=False)
  • turn_on_ps_on: write_digital(name="PS_ON", portnum=0, state=True)
  • read_status: read_digital(name="STATUS", portnum=0)
  • load_bram: load_waveform(path="data/waveform_25-03-2025-15-48-03.yaml")
  • raise_error: raise_exception(e="Not ok")
  • read_status2: read_digital(name="STATUS", portnum=0)
  • output_values: output_values(values=["prev('measure_and_check_signals', 'do_offload')[0][0]", "prev('measure_and_check_signals', 'read_status')", "prev('measure_and_check_signals', 'read_status2')"])

run_measure_and_check_signals

Check Signals

View Sequence Diagram

Format: run_measure_and_check_signals

Example: run_measure_and_check_signals

Description:

Steps:

  • do_offload: single_offload(plot=False)
  • turn_on_ps_on: write_digital(name="PS_ON", portnum=0, state=True)
  • read_status: read_digital(name="STATUS", portnum=0)
  • load_bram: load_waveform(path="data/waveform_25-03-2025-15-48-03.yaml")
  • raise_error: raise_exception(e="Not ok")
  • read_status2: read_digital(name="STATUS", portnum=0)
  • output_values: output_values(values=["prev('measure_and_check_signals', 'do_offload')[0][0]", "prev('measure_and_check_signals', 'read_status')", "prev('measure_and_check_signals', 'read_status2')"])

Back to Index

RS232 API Documentation - NLOS

Back to Index

Overview

This document describes the RS232 API commands available for the NLOS subsystem.

Direct Hardware Control Commands

Interface Control

write_digital

Callback function for the digital output buttons (ToggleButtons).

Format: write_digital <name> <portnum> <state>

Parameters: - name: string - portnum: integer - state: boolean value ("true"/"false" or "1"/"0")

Example: write_digital ONHV 0 true

Returns: Success/error status and the written value

Description: This command directly controls the digital outputs of the control board. It's used to toggle hardware components on and off, such as power supplies, high voltage sources, and pulse generators.

write_analog

Callback function for the analog output buttons (DACGroup).

Format: write_analog <name> <portnum> <value>

Parameters: - name: string - portnum: integer - value: float

Example: write_analog DAC1 2 3.5

Returns: Success/error status and the written value

Description: This command controls analog outputs, allowing precise control of voltage levels for components such as DACs (Digital-to-Analog Converters). It's used for controlling variable parameters like power levels and timing signals.

Adc Control

adc_single_offload

Perform single offload Example command: 'GET adc_single_offload'

Format: adc_single_offload

Example: adc_single_offload

Returns: ADC data or success message

Description: This command reads the current ADC data from BRAM (Block RAM) registers and returns the values. It's useful for checking analog signal values at a specific moment in time.

adc_continuous_offload

Perform single offload Example command: 'GET adc_single_offload'

Format: adc_continuous_offload <state>

Parameters: - state: boolean value ("true"/"false" or "1"/"0")

Example: adc_continuous_offload true

Returns: ADC data or success message

Description: This command controls the continuous reading of ADC data. When enabled, the system will continuously read and transmit ADC values until disabled. This is useful for monitoring analog signals over time.

Available Routines for NLOS

The following routines are registered in the NLOS subsystem and can be executed via RS232:

run_divide_frequency

Divide Frequency

View Sequence Diagram

Format: run_divide_frequency <divider>

Example: run_divide_frequency 123.45

Description:

Steps:

  • Generate Gates: execute_python_script(script_path="data/generate_gates.py", kwargs={'divider': '{divider}'})
  • Gates Load Test Seed: load_gates(path="data/gates_div.yaml")
  • Sleep: pause(seconds=0.2)
  • Gates Write: write_gates()
  • Sleep: pause(seconds=0.2)
  • Select gate regime: select_gate_regime(selected_item="INT Cont.", name="")
  • Sleep: pause(seconds=0.2)
  • Start Gates: start_waveform()

run_check_laser_status

Check Laser status

View Sequence Diagram

Format: run_check_laser_status

Example: run_check_laser_status

Description:

Steps:

  • Check PLD2: execute_routine(routine_name="check_status_pld2")
  • Check PLD1: execute_routine(routine_name="check_status_pld1")
  • Check Idler: execute_routine(routine_name="check_status_idler")
  • Check Seed: execute_routine(routine_name="check_status_seed")

run_arm_laser

Arm Laser

View Sequence Diagram

Format: run_arm_laser <frequency>

Example: run_arm_laser "example_string"

Description:

Steps:

  • Check Laser Status: execute_routine(routine_name="check_laser_status")
  • Disarm laser: execute_routine(routine_name="disarm_laser")
  • Save Bram: get_waveform()
  • Save Gates: get_gates()
  • Select gate regime: select_gate_regime(selected_item="Disabled", name="")
  • Sleep: pause(seconds=0.2)
  • Read ADC: start_acquisition()
  • SET HVS: write_analog(name="HVS", portnum=0, value="{HVS}.get('{frequency}')")
  • SET UnegB: write_analog(name="UnegB", portnum=0, value="{UnegB}.get('{frequency}')")
  • SET OPT_ATT: write_analog(name="OPT_ATT", portnum=0, value="{OPT_ATT}.get('{frequency}')")
  • SET DILS: write_analog(name="DILS", portnum=1, value="{DILS}.get('{frequency}')")
  • SET Iset: write_analog(name="Iset", portnum=3, value="{Iset}.get('{frequency}')")
  • Seed Test: execute_routine(routine_name="seed_test", routine_params={'frequency': '{frequency}'})
  • Idler Test: execute_routine(routine_name="idler_test", routine_params={'frequency': '{frequency}'})
  • Gates Load Test Seed: load_gates(path="data/default_gates_div.yaml")
  • Sleep: pause(seconds=0.2)
  • Gates Write: write_gates()
  • Sleep: pause(seconds=0.2)
  • Select gate regime: select_gate_regime(selected_item="INT Cont.", name="")
  • Sleep: pause(seconds=0.2)
  • Start Gates: start_waveform()
  • PULSE1 PLD1: write_digital(name="PULSE1", portnum=2, state=True)

run_disarm_laser

Disarm laser

View Sequence Diagram

Format: run_disarm_laser

Example: run_disarm_laser

Description:

Steps:

  • PULSE1 PLD2: write_digital(name="PULSE1", portnum=3, state=False)
  • PULSE1 PLD1: write_digital(name="PULSE1", portnum=2, state=False)
  • ON11V: write_digital(name="ON11V", portnum=1, state=False)
  • ON11V Off: write_digital(name="ON11V", portnum=0, state=False)
  • ONHV Off: write_digital(name="ONHV", portnum=0, state=False)

run_shutdown_laser

Shutdown Laser

View Sequence Diagram

Format: run_shutdown_laser

Example: run_shutdown_laser

Description:

Steps:

  • Turn off PLD2: execute_routine(routine_name="pld2_off")
  • Turn off PLD1: execute_routine(routine_name="pld1_off")
  • Turn off Idler: execute_routine(routine_name="idler_off")
  • Turn off Seed: execute_routine(routine_name="seed_off")

run_emission_on

Emission ON

View Sequence Diagram

Format: run_emission_on

Example: run_emission_on

Description:

Steps:

  • Check Laser Status: execute_routine(routine_name="check_laser_status")
  • Check PLD1 Imoni: read_analog(name="Imoni", portnum=2)
  • Raise Exception: raise_exception(e="Emission on Error: Laser not armed")
  • PULSE1 PLD2: write_digital(name="PULSE1", portnum=3, state=True)

run_emission_off

Emission OFF

View Sequence Diagram

Format: run_emission_off

Example: run_emission_off

Description:

Steps:

  • PULSE1 PLD2: write_digital(name="PULSE1", portnum=3, state=False)

Back to Index

Example Usage Sequences

Complete Startup Sequence

run_emission_on

Safe Shutdown Sequence

run_shutdown_laser
run_emission_off

Status Check and Monitoring

run_measure_and_check_signals
adc_single_offload

Manual Control Example

write_digital PS_ON 0 true
write_digital ON11V 0 true
write_digital ONHV 0 true
write_analog DAC1 2 3.5

Data Collection Sequence

adc_continuous_offload true
# Monitor data for some time
adc_continuous_offload false

Back to Index

Troubleshooting

Connection Issues

  • Verify connection parameters (baud rate, data bits, etc.)
  • Check physical connections including cable integrity
  • Ensure no other applications are using the same port

Command Execution Problems

  • Ensure commands are properly formatted with correct spacing
  • Check parameter types and ranges
  • Verify command spelling and case sensitivity

Hardware Communication

  • Check the laser system logs for detailed error messages
  • Verify that hardware components are powered and operational
  • Ensure the UART connection is properly configured on both systems

System State Issues

  • If system is in an unknown state, perform a full shutdown and restart
  • Use status check commands to diagnose component states
  • Check hardware interlocks and safety systems

Debugging Tips

  • Enable debug logging on both the client and server side
  • Send commands one at a time and verify responses
  • Monitor system behavior through ADC readings
  • Check log files for detailed error information

Back to Index

Implementation Details

The RS232 API is implemented using a UART router that:

  1. Listens for incoming commands on the configured UART port
  2. Parses the command and extracts parameters
  3. Executes the corresponding function or routine
  4. Returns the result to the sender

All routines marked with register-api: true in their YAML configuration are automatically registered for RS232 access with the prefix run_.

The system uses regex pattern matching to identify commands and extract parameters. Function handlers are registered for each command pattern using the @uart_route decorator or through automatic registration of routines.

Back to Index