### Build and Install OpenSuperClone

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Commands for installing dependencies, building packages, and managing the OSCDriver.

```bash
# Install dependencies (Debian/Ubuntu)
sudo apt install cmake gcc gettext libconfig-dev libgtk-3-dev libusb-dev pkg-config

# Build DEB/RPM package (recommended)
./package.sh
# Packages are created in ./package/
sudo dpkg -i ./package/opensuperclone_*.deb

# Build and run locally (without system installation)
./build.sh
sudo ./Release/opensuperclone
./Release/oscviewer

# Build and install to /usr/
sudo ./install.sh
sudo opensuperclone
oscviewer

# Uninstall
sudo ./uninstall.sh

# Manual OSCDriver installation with DKMS
sudo cp -r OSCDriver-x.x.x /usr/src/
sudo dkms install OSCDriver/x.x.x

# Manual OSCDriver build
cd ./Release/src/OSCDriver-x.x.x
make
sudo make install
```

--------------------------------

### Build and Install System-wide

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Compiling from Source

Compiles and installs the project to /usr/ and manages the kernel driver.

```Bash
# Build OpenSuperClone for Release and install to /usr/
$ ./install.sh

# Run OpenSuperClone
$ sudo opensuperclone

# Run OSCViewer
$ oscviewer

# Uninstall OpenSuperClone (including the kernel driver)
$ ./uninstall.sh
```

--------------------------------

### Install Project Files

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscviewer/CMakeLists.txt

Defines installation rules for the executable, localization files, and desktop entry.

```cmake
# Install executable
install(TARGETS oscviewer RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

# Install language files
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/locale
        DESTINATION share
)

# Install desktop file
install(FILES ${CMAKE_SOURCE_DIR}/res/oscviewer.desktop
        DESTINATION share/applications
)
```

--------------------------------

### Build and Run Locally

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Compiling from Source

Compiles the project for local execution without system-wide installation.

```Bash
# Build OpenSuperClone for Release and install to ./Release
$ ./build.sh

# Run OpenSuperClone
$ sudo ./Release/opensuperclone

# Run OSCViewer
$ ./Release/oscviewer
```

--------------------------------

### Configure USB Relay Power Cycling

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Setup steps for automatic power cycling using external relay hardware.

```bash
# In OpenSuperClone GUI:
# 1. Connect relay board via USB
# 2. Settings -> Relay Settings
```

--------------------------------

### Install OSCDriver Manually

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Compiling from Source

Compiles and installs the kernel module directly from the source directory.

```Bash
$ cd ./Release/src/OSCDriver-x.x.x
$ make
$ sudo make install
```

--------------------------------

### Execute ATA Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Examples of performing device identification using 28-bit and 48-bit ATA command structures.

```Bash
# Perform ata_identify_device command
buffersize 512
setreadpio
ata28cmd 0 0 0 0 0 0xa0 0xec

# Print the result of the command
printbuffer 0 512
```

```Bash
# Perform ata_identify_device command
buffersize 512
setreadpio
ata48cmd 0 0 0 0 0 0xa0 0xec

# Print the result of the command
printbuffer 0 512
```

--------------------------------

### Read Sector using 48-bit ATA Command

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Example of reading a sector using a 48-bit ATA command, suitable for drives larger than 128GB. Note the different command signature.

```bash
# For 48-bit commands (drives > 128GB):
# ata48cmd features count lba_high lba_mid lba_low device command
buffersize 512
setreadpio
ata48cmd 0 1 0 0 0 0xa0 0x24
```

--------------------------------

### Install OSCDriver with DKMS

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Compiling from Source

Registers the kernel module with DKMS for automatic management.

```Bash
# Copy the OSCDriver source to /usr/src
$ sudo cp -r OSCDriver-x.x.x /usr/src/

# Install OSCDriver
$ sudo dkms install OSCDriver/x.x.x
```

--------------------------------

### SCSI Read Capacity (10) Command

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Executes the SCSI Read Capacity (10) command to get drive capacity information. Sets direction, buffer size, and command parameters.

```bash
# SCSI Read Capacity (10) command
direction from
buffersize 8
scsi10cmd 0x25 0 0 0 0 0 0 0 0 0
```

--------------------------------

### Manually populate the buffer

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Define raw hex data to be placed in the buffer starting at a specific offset. Rows can include additional relative offsets using the colon syntax.

```Bash
# Start setting the buffer at offset 128 (0x80)
setbuffer 0x80
  0  1  2  3  4  5  6  7
  8  9  a  b  c  d  e  f
  10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
  # The next line will jump to offset 256 (0x100)
  80: 20 21 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
endbuffer
```

--------------------------------

### Perform arithmetic and variable assignment with seti

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Assign integer values or results of mathematical operations to variables starting with $. Variables are 64-bit signed integers.

```Bash
# Set the value of $a to 3
seti $a = 3

# Set the value of $b to the value of $a + 1 = 4
seti $b = $a + 1

# Set the value of $c to the value of $a * $b = 12
seti $c = $a * $b
```

--------------------------------

### Get Total Addressable Sectors

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Retrieves the total number of addressable sectors based on 48-bit LBA support. Uses different buffer offsets for 28-bit and 48-bit modes.

```bash
# Get total addressable sectors
if $extended = 1
  seti $addressable = buffer 200 qw
else
  seti $addressable = buffer 120 dw
endif
echo "Total sectors: " $addressable
```

--------------------------------

### Run OpenSuperClone and OSCViewer

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Commands to launch the GUI, interactive CLI, or log viewer.

```bash
# Run OpenSuperClone GUI (requires root)
sudo opensuperclone

# Run OpenSuperClone in interactive CLI mode
sudo opensuperclone --tool

# Run OSCViewer (log file viewer, no root required)
oscviewer
```

--------------------------------

### Subroutine Definition and Call

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Demonstrates defining and calling subroutines using `subroutine` and `gosub`. Enables code modularity and reuse.

```bash
# Subroutines
subroutine my_function
  echo "Inside subroutine"
endsubroutine

gosub my_function
```

--------------------------------

### Assign Variables and Output

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Demonstrates basic variable assignment and output using `seti`, `sets`, and `echo` commands. Use for simple scripting tasks.

```bash
# Variable assignment
seti $a = 3
seti $b = $a + 1
seti $c = $a * $b
sets $string = "Hello World"

# Output
echo "The value is " $a
echo "String: " $string
```

--------------------------------

### Generate Header from Resources

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscviewer/CMakeLists.txt

Uses xxd to convert a Glade file into a C header file.

```cmake
add_custom_command(
    OUTPUT oscviewer_glade.h
    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/oscviewer.glade oscviewer.glade
    COMMAND xxd -i oscviewer.glade oscviewer_glade.h
    DEPENDS oscviewer.glade
)
LIST(APPEND RESOURCES oscviewer_glade.h)
```

--------------------------------

### Get Current Drive Status

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Retrieves the current status and error registers of the drive after an operation. The results are stored in `ata_return_status` and `ata_return_error`.

```bash
# Get current drive status
getstatus
echo "Status register: " $ata_return_status
echo "Error register: " $ata_return_error
```

--------------------------------

### Looping with While

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Shows how to implement loops using the `while` construct. Suitable for repetitive tasks until a condition is met.

```bash
# Loops
seti $count = 1
while $count <= 10
  echo "Count: " $count
  seti $count = $count + 1
done
```

--------------------------------

### Perform Basic Clone Operation

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Steps for initiating a clone operation via the GUI and an overview of the recovery phases.

```bash
# Start OpenSuperClone GUI
sudo opensuperclone

# In the GUI:
# 1. File -> New Project (create a log file to save recovery progress)
# 2. Drives -> Choose Source Drive (select the drive to recover)
# 3. Drives -> Choose Destination (select image file or target drive)
# 4. Click "Connect" to connect to the source drive
# 5. Click "Start" to begin the clone operation

# The recovery progresses through multiple phases:
# Phase 1: Forward copy with error skipping
# Phase 2: Backward copy with error skipping
# Phase 3: Forward copy with rate-based skipping
# Phase 4: Forward copy without skipping
# Trimming: Process failed blocks sector by sector
# Scraping: Read remaining non-scraped sectors
# Retrying: Retry all bad sectors
```

--------------------------------

### Run OpenSuperClone in CLI mode

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Command-Line-Interface

Executes the program in interactive mode using root privileges.

```bash
$ sudo opensuperclone --tool
```

--------------------------------

### Configure and Build Executable

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscviewer/CMakeLists.txt

Configures the header file and defines the executable target with its dependencies.

```cmake
configure_file(config.h.in config.h)

# Add build target OSCViewer
add_executable(oscviewer ${SOURCES} ${RESOURCES} ${MO_FILES})

# Include resources
target_include_directories(oscviewer PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
```

--------------------------------

### Define Source Files

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscviewer/CMakeLists.txt

Sets the source files for the project.

```cmake
set(SOURCES
    oscviewer.c
)
```

--------------------------------

### System and Utility Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for logging, time management, and disk control.

```APIDOC
## writelog
### Description
Appends a string variable to a text file. If the file does not exist, it is created.
### Parameters
- **filename** (string) - Required - The target file.
- **string** (variable) - Required - The variable to write.

## gettime
### Description
Retrieves the current time and date, setting the $time (microseconds since Epoch) and $date (string) variables.

## reopendisk
### Description
Closes and reopens the current disk (passthrough only). Performs a soft reset on the drive.
```

--------------------------------

### Configure Virtual Disk Mode

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Steps to expose a recovery target as a block device for third-party software.

```bash
# In OpenSuperClone GUI:
# 1. Create project and select source/destination as normal
# 2. Click "Virtual Mode 1" (or 2-5 depending on needs)
# 3. Click "Connect" then "Start"
# 4. The virtual device appears at /dev/oscdriver
# 5. Mount or scan with recovery software

# Virtual Mode Options:
# Mode 1: Uses all recovery phases starting with Phase 4
# Mode 2: Only Phase 4, no further chunk processing
# Mode 3: Same as Mode 2 with adaptive read size for sequential reads
# Mode 4: Reads only from destination (no source access)
# Mode 5: Returns zeroed data (for testing)

# Use third-party recovery tool on the virtual device
dmde /dev/oscdriver
```

--------------------------------

### Build Package

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Compiling from Source

Generates DEB and RPM packages for the project.

```Bash
# Build the OpenSuperClone package for Release
$ ./package.sh
```

--------------------------------

### Execute Clone Mode via Command Line

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Automated operations using scripts and specific ATA/SCSI commands.

```bash
# Run a script from the command line
sudo opensuperclone --tool -t /dev/sda -f /path/to/script.osc

# Example: Identify device information
sudo opensuperclone --tool -t /dev/sda -f ata_identify_device.osc

# Example: Read SMART data
sudo opensuperclone --tool -t /dev/sda -f ata_smart_data.osc

# Example: Read specific sectors
sudo opensuperclone --tool -t /dev/sda -f ata28_read_sectors_pio.osc \
  sector=0 count=1 file=="sector0.bin"
```

--------------------------------

### Copy Between Buffer and Scratchpad

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Illustrates copying data between the main buffer and the scratchpad memory using `copybuffertoscratchpad` and `copyscratchpadtobuffer`.

```bash
# Copy between buffer and scratchpad
copybuffertoscratchpad 0 0 512
copyscratchpadtobuffer 0 0 512
```

--------------------------------

### Configure Direct Access Modes

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Instructions for bypassing OS drivers to communicate directly with storage hardware.

```bash
# Direct AHCI Mode (for SATA drives)
# - Requires drive to be hidden from OS
# - SATA controller must be in AHCI mode
# In GUI: Drives -> Mode -> Direct AHCI -> Choose Source

# Direct IDE Mode (for PATA drives or SATA in IDE emulation)
# - Requires drive to be hidden from OS
# In GUI: Drives -> Mode -> Direct IDE -> Choose Source

# Direct USB Mode (for USB drives/flash drives)
# - Drive automatically hidden when selected
# - Provides ability to reset USB devices on timeout
# In GUI: Drives -> Mode -> Direct USB -> Choose Source

# Direct USB ATA Mode (for USB-attached conventional HDDs)
# - Same as Direct USB but performs ATA commands
# - Do not use for flash drives (may lock up device)
# In GUI: Drives -> Mode -> Direct USB ATA -> Choose Source
```

--------------------------------

### Manage Log Files and OSCViewer

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Commands and GUI operations for managing recovery logs and visualizing data with OSCViewer.

```bash
# In OpenSuperClone GUI:

# Create new project
# File -> New Project -> Save as recovery.log

# Open existing project
# File -> Open Project -> Select .log file

# Import ddrescue map file
# File -> Import ddrescue Log (Map) File

# Export to ddrescue format
# File -> Export ddrescue Log (Map) File

# Domain files (limit recovery to specific areas)
# File -> New Domain File
# File -> Load Domain File
# File -> Add to Domain from DMDE bytes file

# View log file with OSCViewer
oscviewer recovery.log

# OSCViewer options:
# - View -> Main Panel Resolution (adjust detail level)
# - View -> Highlight Good Data (show partial reads)
# - View -> Show Bad Head (mark detected bad head patterns)
# - View -> Show High-Time (highlight slow sectors)
```

--------------------------------

### File I/O Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for reading from and writing to files using the buffer.

```APIDOC
## writebuffer

### Description
Write the buffer or part of the buffer to a file.

### Parameters
#### Query Parameters
- **filename** (string) - Required - Name of the file to write to
- **bufferoffset** (integer) - Required - Byte offset in the buffer
- **fileoffset** (integer) - Required - Byte offset in the file
- **size** (integer) - Required - Size in bytes to be written

## readbuffer

### Description
Read a part of a file to the buffer.

### Parameters
#### Query Parameters
- **filename** (string) - Required - Name of the file to read from
- **bufferoffset** (integer) - Required - Byte offset in the buffer
- **fileoffset** (integer) - Required - Byte offset in the file
- **size** (integer) - Required - Size in bytes to be read
```

--------------------------------

### Control Flow with If/Elseif/Else

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Illustrates conditional execution using `if`, `elseif`, and `else` statements. Useful for creating logic based on variable values.

```bash
# Control flow
if $a > 1
  echo "a is greater than 1"
elseif $a = 1
  echo "a equals 1"
else
  echo "a is less than 1"
endif
```

--------------------------------

### Link GTK3 and Libconfig Dependencies

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscviewer/CMakeLists.txt

Configures include directories, library paths, and compiler flags for GTK3 and libconfig.

```cmake
# Add GTK dependency
target_include_directories(oscviewer PRIVATE ${GTK3_INCLUDE_DIRS})
target_link_directories(oscviewer PRIVATE ${GTK3_LIBRARY_DIRS})
target_compile_options(oscviewer PRIVATE ${GTK3_CFLAGS_OTHER})
target_link_libraries(oscviewer ${GTK3_LIBRARIES})

# Add libconfig dependency
target_include_directories(oscviewer PRIVATE ${LIBCONFIG_INCLUDE_DIRS})
target_link_directories(oscviewer PRIVATE ${LIBCONFIG_LIBRARY_DIRS})
target_compile_options(oscviewer PRIVATE ${LIBCONFIG_CFLAGS_OTHER})
target_link_libraries(oscviewer ${LIBCONFIG_LIBRARIES})

target_compile_options(oscviewer PRIVATE ${CC_OPTIONS})
```

--------------------------------

### Configure OSCDriver Build

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscdriver/CMakeLists.txt

Configures the build process by setting source files, generating configuration headers, and setting up DKMS and package scripts.

```cmake
set(
    SOURCES
    oscdriver.c
)

# Generate config file for OSCDriver
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/config.h.in ${CMAKE_CURRENT_BINARY_DIR}/config.h)

# Configure the DKMS config file
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/dkms.conf.in ${CMAKE_CURRENT_BINARY_DIR}/dkms.conf)

# Configure the postinst and prerm scripts for the DEB package and put them in the root of the build directory
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/postinst.in ${CMAKE_BINARY_DIR}/postinst)
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/prerm.in ${CMAKE_BINARY_DIR}/prerm)

# Install the driver to the source directory
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/config.h DESTINATION ${CMAKE_INSTALL_PREFIX}/src/oscdriver-${OSC_DRIVER_VERSION})
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/dkms.conf DESTINATION ${CMAKE_INSTALL_PREFIX}/src/oscdriver-${OSC_DRIVER_VERSION})
install(FILES ${SOURCES} DESTINATION ${CMAKE_INSTALL_PREFIX}/src/oscdriver-${OSC_DRIVER_VERSION})
install(FILES Makefile DESTINATION ${CMAKE_INSTALL_PREFIX}/src/oscdriver-${OSC_DRIVER_VERSION})
```

--------------------------------

### callcommand

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Executes a command line command.

```APIDOC
## callcommand

### Description
Perform a command line command.

### Parameters
#### Path Parameters
- **command** (string) - Required - The command line command to be performed.
```

--------------------------------

### Extract Values from Buffer

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Demonstrates extracting single bytes, words, dwords, and qwords from a buffer using the `buffer` command with different access sizes.

```bash
# Extract values from buffer
seti $byte_val = buffer 0
seti $word_val = buffer 0 w
seti $dword_val = buffer 0 dw
seti $qword_val = buffer 0 qw
```

--------------------------------

### Compile Localization Files

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/oscviewer/CMakeLists.txt

Iterates through locale directories and compiles .po files into .mo files using msgfmt.

```cmake
file(GLOB PO_LANGS LIST_DIRECTORIES true ${CMAKE_CURRENT_SOURCE_DIR}/locale/*)
foreach(PO_LANG IN ITEMS ${PO_LANGS})
    if(IS_DIRECTORY ${PO_LANG})
        get_filename_component(PO_LANG_NAME ${PO_LANG} NAME)
        add_custom_command(
            OUTPUT locale/${PO_LANG_NAME}/LC_MESSAGES/oscviewer.mo
            COMMAND ${CMAKE_COMMAND} -E make_directory locale/${PO_LANG_NAME}/LC_MESSAGES
            COMMAND msgfmt -o locale/${PO_LANG_NAME}/LC_MESSAGES/oscviewer.mo ${PO_LANG}/oscviewer.po
        )
        LIST(APPEND MO_FILES locale/${PO_LANG_NAME}/LC_MESSAGES/oscviewer.mo)
    endif()
endforeach()
```

--------------------------------

### Subroutine Definition and Execution

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Define subroutines with `subroutine` and end with `endsubroutine`. Call them using `gosub`.

```Bash
subroutine show_sense_buffer
  if $direct_mode = 0
    echo "Sense buffer:"
    printsensebuffer 0 $io_sb_len_wr
  endif
endsubroutine
```

```Bash
ata28cmd 0 0 0 0 0 0xa0 0xec
gosub show_ata_return
printbuffer 0 512
```

```Bash
subroutine do_something
  if $error_level != 0
    returnsub
  endif
  printbuffer 0 512
endsubroutine
```

--------------------------------

### Perform Soft Reset and Reopen Disk

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Initiates a soft reset of the drive and demonstrates reopening the disk, which can perform a passthrough mode reset.

```bash
# Perform soft reset
softreset

# Reopen disk (passthrough mode reset)
reopendisk
```

--------------------------------

### Execute system commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Runs a command line command. Multi-word commands must be passed via a string variable.

```Bash
# Perform the command "ls -a"
sets $command = "ls -a"
callcommand $command
```

--------------------------------

### Script Management Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for loading, including, and navigating between script files.

```APIDOC
## Configuration: loadscript, previousscript, include

### Description
Commands to manage script execution flow and file inclusion.

### Parameters
- **loadscript** (string) - Loads a new script file into memory.
- **previousscript** (void) - Returns to the previously loaded script.
- **include** (string) - Appends a script file to the end of the current script.
```

--------------------------------

### Log Data to File

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Appends string variables to a text file, creating the file if it does not exist.

```Bash
sets $line1 = "This is the first line"
sets $line2 = "This is the second line"
writelog logfile.txt $line1
writelog logfile.txt $line2
```

--------------------------------

### Check Direct Mode Configuration

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Conditional check to determine if the system is operating in direct IO mode or passthrough mode.

```bash
if $direct_mode = 1
  echo "Using direct IO mode"
else
  echo "Using passthrough mode"
endif
```

--------------------------------

### Buffer Management Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for manipulating, sizing, and clearing the internal data buffer.

```APIDOC
## printbuffer

### Description
Prints the buffer to the screen.

### Parameters
#### Query Parameters
- **offset** (integer) - Required - Starting buffer offset
- **size** (integer) - Required - Number of bytes to be printed

### Request Example
printbuffer 0 256

## stringtobuffer

### Description
Puts a string into the buffer contents.

### Parameters
#### Query Parameters
- **offset** (integer) - Required - Buffer offset
- **size** (integer) - Required - Maximum copy size
- **$string** (string) - Required - String variable name

## buffersize

### Description
Sets a new buffer size and erases current contents.

### Parameters
#### Query Parameters
- **size** (integer) - Required - New size of the buffer in bytes (Max 33554432)

## clearbuffer

### Description
Clears the entire buffer contents to zero.
```

--------------------------------

### Display or Write Sector Data

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Shows how to display the contents of the buffer after reading a sector or write it to a file. Use `printbuffer` or `writebuffer`.

```bash
# Display or save results
printbuffer 0 512
# Or write to file:
# writebuffer sector0.bin 0 0 512
```

--------------------------------

### Print SCSI Sense Buffer

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Displays the contents of the SCSI return sense buffer.

```Bash
# Display the contents of the sense buffer that was returned, if any
printsensebuffer 0 $io_sb_len_wr
```

--------------------------------

### Print Buffer Contents

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Displays a specified range of bytes from the current buffer.

```Bash
# Show the first 256 bytes of the buffer
printbuffer 0 256
```

--------------------------------

### userinput

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Pauses execution to capture user input from the keyboard.

```APIDOC
## userinput

### Description
Get user input from keyboard and store it in a variable.

### Parameters
#### Path Parameters
- **variable** (string) - Required - The string variable where the user input is placed.
```

--------------------------------

### Scratchpad Data Manipulation

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for interacting with the scratchpad, including printing, string conversion, clearing, resizing, writing to files, reading from files, and copying to/from the buffer.

```Bash
# Copy 512 bytes from scratchpad to buffer
copyscratchpadtobuffer 0 0 512
```

```Bash
# Copy 512 bytes from the buffer to the scratchpad
copybuffertoscratchpad 0 0 512
```

--------------------------------

### Execute SCSI 10 Command

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Performs a 10-byte SCSI command.

```Bash
# Perform SCSI capacity 10 command
direction from
scsi10cmd 0x25 0 0 0 0 0 0 0 0 0
```

--------------------------------

### Display Sense Buffer and Check Status

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Shows how to display the SCSI sense buffer and check the command status after a SCSI operation. Useful for error handling.

```bash
# Display sense buffer after command
printsensebuffer 0 $io_sb_len_wr

# Check command status
if $command_status != 0
  echo "Command failed with status: " $command_status
endif
```

--------------------------------

### Toggle hex and decimal output modes

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Use hex to force subsequent output to hexadecimal format, and decimal to revert to default behavior. Be cautious as hex mode persists until explicitly disabled.

```Bash
seti $number = 0x7f
echo "The number in decimal is " $number
hex
echo "The number in hex is 0x" $number
decimal
```

--------------------------------

### SCSI Read Capacity (16) Command

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Executes the SCSI Read Capacity (16) command for extended capacity information. Requires a larger buffer size.

```bash
# SCSI Read Capacity (16) command
direction from
buffersize 32
scsi16cmd 0x9e 0x10 0 0 0 0 0 0 0 0 0 0 0 0x20 0 0
```

--------------------------------

### Read Sector 0 (MBR) using 28-bit PIO

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Reads the first sector (MBR) of a drive using a 28-bit ATA PIO command. Sets buffer size, clears buffer, and configures the command parameters.

```bash
# Read sector 0 (MBR) using 28-bit PIO command
seti $sector = 0
seti $count = 1
seti $buffersize = $count * 512
buffersize $buffersize
clearbuffer

# Calculate LBA bytes
seti $LBAlow = $sector & 0xff
seti $temp = $sector > 8
seti $LBAmid = $temp & 0xff
seti $temp = $sector > 16
seti $LBAhigh = $temp & 0xff
seti $temp = $sector > 24
seti $LBAdevice = $temp & 0x0f

# Setup and execute command
setreadpio
seti $device = 0xe0
seti $device = $device | $LBAdevice
ata28cmd 0 $count $LBAlow $LBAmid $LBAhigh $device 0x20
```

--------------------------------

### setbuffer

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Manually populates the data buffer with hex values.

```APIDOC
## setbuffer

### Description
Sets the contents of the data buffer starting at a specified offset. Data is provided in hex format until the endbuffer command is reached.

### Parameters
- **offset** (number) - Required - The starting byte location in the buffer.

### Request Example
setbuffer 0x80
  0  1  2  3
endbuffer
```

--------------------------------

### Retrieve System Time

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Captures the current epoch time and date into variables for logging or duration calculation.

```Bash
# Display the time since Epoch and the current date
gettime
echo "Time: " $time
echo "Date: " $date

# Display the time elapsed
gettime
seti $start_time = $time

# Do some program stuff here that takes time
gettime
seti $elapsed_time = $time - start_time
echo "Time elapsed: " $elapsed_time
```

--------------------------------

### SCSI and ATA Command Execution

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for executing SCSI/ATA passthrough operations and managing sense buffers.

```APIDOC
## direction

### Description
Set the direction of the data transfer.

### Parameters
#### Query Parameters
- **direction** (string) - Required - none, to, from, or tofrom

## scsi10cmd

### Description
Perform a SCSI 10 command.

### Parameters
#### Query Parameters
- **b0-b9** (hex) - Required - Bytes of the command

## printsensebuffer

### Description
Prints the SCSI return sense buffer to the screen.

### Parameters
#### Query Parameters
- **offset** (integer) - Required - Sense buffer offset
- **size** (integer) - Required - Number of bytes to be printed
```

--------------------------------

### Execute SCSI 16 Command

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Performs a 16-byte SCSI command.

```Bash
# Perform SCSI capacity 16 command
direction from
scsi16cmd 0x94 0x10 0 0 0 0 0 0 0 0 0 0 0 0x12 0 0
```

--------------------------------

### Check for Libconfig Dependency

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/CMakeLists.txt

This command checks for the libconfig library, used for parsing configuration files.

```cmake
pkg_check_modules(LIBCONFIG REQUIRED libconfig)
```

--------------------------------

### OSCScript Echo Command

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Prints text and variables to the screen. Variables must be placed outside of quoted strings, with spaces separating quotes and variables.

```Bash
echo "This will print the variable a=" $a " and then the variable b=" $b
echo "This will print single 'quotes' within the line"
```

--------------------------------

### Find PkgConfig Dependency

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/CMakeLists.txt

Use this command to find the PkgConfig dependency, which is required for managing package configurations.

```cmake
find_package(PkgConfig REQUIRED)
```

--------------------------------

### Extract String from Buffer

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Shows how to extract a null-terminated string from a specified offset and length within the buffer.

```bash
# Extract string from buffer
sets $string = buffer 54 40
```

--------------------------------

### Control Flow Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for conditional logic execution.

```APIDOC
## if
### Description
Conditional statement. Executes code between 'if' and 'endif' if the condition is true.
### Parameters
- **value1** (number/string) - Required - First operand.
- **condition** (operator) - Required - Comparison operator (<, >, =, !=, <=, =>).
- **value2** (number/string) - Required - Second operand.

## endif
### Description
Marks the end of an if statement.

## else
### Description
Alternative block processed when the if condition is false.
```

--------------------------------

### sets

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Sets a string variable or extracts a portion of the buffer into a string.

```APIDOC
## sets

### Description
Assigns a string value to a variable or copies a specific length of bytes from the buffer into a string variable.

### Parameters
- **$variable** (string) - Required - The variable name starting with $.
- **value/source** (mixed) - Required - The string content or buffer location and length.

### Request Example
sets $string = "a=" $a " and b=" $b
sets $string = buffer 54 40
```

--------------------------------

### Timeout Configuration Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands to configure various timeout thresholds for ATA commands and direct IO operations.

```APIDOC
## Configuration: softtimeout, resettimeout, busytimeout, generaltimeout

### Description
These commands configure timeout durations for ATA commands and direct IO operations. Values are specified in microseconds.

### Parameters
- **softtimeout** (integer) - Time to wait before sending a soft reset. Default: 15000000.
- **resettimeout** (integer) - Time to wait for the drive to be ready after a soft reset. Default: 15000000.
- **busytimeout** (integer) - Time to wait if the device is busy before issuing a command. Default: 15000000.
- **generaltimeout** (integer) - Time to wait for a command to finish. Default: 30000000.
```

--------------------------------

### Looping with while and done

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Implement loops using `while` and `done`. The condition is re-evaluated after each iteration.

```Bash
# Count from 1 to 10
seti $count = 1
while $count <= 10
  echo "The count is " $count
  seti $count = $count + 1
done
```

--------------------------------

### Conditional Statements: if, elseif, else, endif

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Use `if`, `elseif`, `else`, and `endif` for conditional execution. `elseif` and `else` are optional.

```Bash
if $a > 10
  echo "a is greater than 10"
elseif $a < 0
  echo "a is less than 0"
elseif $a = 5
  echo "a is equal to 5"
else
  echo "a is between 0 and 10 but is not 5"
endif
```

--------------------------------

### Find Gettext Dependency

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/CMakeLists.txt

Use this command to find the Gettext dependency, essential for internationalization and localization.

```cmake
find_package(Gettext REQUIRED)
```

--------------------------------

### Set Buffer Size

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Configures the buffer size in bytes, which clears existing buffer contents.

```Bash
# Increase the buffer size to 4096
buffersize 4096
```

--------------------------------

### Set Timeout Values

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Configures various timeout durations for different operations, such as general, soft, reset, and busy timeouts. Values are in microseconds.

```bash
# Set timeout values (in microseconds)
generaltimeout 30000000   # 30 seconds general timeout
softtimeout 15000000      # 15 seconds before soft reset
resettimeout 15000000     # 15 seconds wait after reset
busytimeout 15000000      # 15 seconds busy wait timeout
```

--------------------------------

### Write Buffer to File

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Writes the contents of the buffer to a specified file. Requires filename, buffer offset, file offset, and size.

```bash
# Write buffer to file
writebuffer output.bin 0 0 512
```

--------------------------------

### Control Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for script termination and number formatting control.

```APIDOC
## exit / end / hex / decimal

### Description
- **exit number**: Terminates script with a specific exit code (0-255).
- **end**: Terminates script with exit code 0.
- **hex**: Forces subsequent output and processing to interpret numbers as hexadecimal.
- **decimal**: Reverts number processing to decimal.
```

--------------------------------

### ATA Identify Device Command

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Executes the ATA Identify Device command (0xEC) to retrieve drive information. Requires setting buffer size and read mode.

```bash
# ATA Identify Device Command
buffersize 512
setreadpio
ata28cmd 0 0 0 0 0 0xa0 0xec
```

--------------------------------

### Check 48-bit LBA Support

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Determines if a drive supports 48-bit LBA by checking a specific word in the Identify Device data. Uses bitwise operations.

```bash
# Check 48-bit LBA support
seti $tempnum = buffer 167
seti $extended = $tempnum & 4
seti $extended = $extended > 2
echo "48-bit LBA support: " $extended
```

--------------------------------

### Check for GTK3 Dependency

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/CMakeLists.txt

This command checks for the GTK3 development files, which are necessary for building GTK+ 3 applications.

```cmake
pkg_check_modules(GTK3 REQUIRED gtk+-3.0)
```

--------------------------------

### Set Buffer Contents Manually

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Populates a buffer with specific hexadecimal values using `setbuffer` and `endbuffer`. Useful for creating custom data payloads.

```bash
# Set buffer contents manually (hex values)
setbuffer 0
  00 01 02 03 04 05 06 07
  08 09 0a 0b 0c 0d 0e 0f
  80: 10 11 12 13 14 15 16 17
endbuffer
```

--------------------------------

### Scratchpad Operations: setscratchpad, endscratchpad

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Manually set scratchpad contents with `setscratchpad` and end with `endscratchpad`. Supports values greater than 255.

--------------------------------

### Copy String to Buffer

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Copies a string variable into the buffer at a specific offset with a size limit.

```Bash
sets $string = "This is a string"

# Copy the whole string (up to 64 bytes) to the buffer starting at offset 0x10
stringtobuffer 0x10 64 $string

# Copy only the first 7 characters to the beginning of the buffer
stringtobuffer 0 7 $string
```

--------------------------------

### Display Control Commands

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for controlling terminal display output.

```APIDOC
## Configuration: upline

### Description
Moves the cursor up one line for display purposes, useful for preventing screen scrolling.
```

--------------------------------

### Write Buffer to File

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Writes a portion of the buffer to a specified file at a given offset.

```Bash
# Write the first 512 bytes of the buffer to the file image.bin
writebuffer image.bin 0 0 512

# Write 512 bytes to the second sector of the file
writebuffer image.bin 0 512 512
```

--------------------------------

### Check for LibUSB Dependency

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/CMakeLists.txt

This command checks for the LibUSB library, which is required for USB device communication.

```cmake
pkg_check_modules(LIBUSB REQUIRED libusb)
```

--------------------------------

### OSCScript Case Sensitivity

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands must be entirely uppercase or entirely lowercase; mixed casing is not permitted.

```Bash
# Valid syntax:
seti $a = 1
SETI $a = 1

# Invalid syntax:
SETi $a = 1
```

--------------------------------

### Add Subdirectories to Build

Source: https://github.com/ispillmydrink/opensuperclone/blob/main/src/CMakeLists.txt

These commands add subdirectories to the build process, indicating separate modules or components of the project.

```cmake
add_subdirectory(opensuperclone)
```

```cmake
add_subdirectory(oscdriver)
```

```cmake
add_subdirectory(oscviewer)
```

--------------------------------

### usleep

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Pauses execution for a specified number of microseconds.

```APIDOC
## usleep

### Description
Sleep for x amount of microseconds.

### Parameters
#### Path Parameters
- **microseconds** (integer) - Required - Duration to sleep.
```

--------------------------------

### OSCScript Syntax Spacing

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands, operators, operands, and variables must be separated by a space.

```Bash
# Valid syntax:
seti $a = 1

# Invalid syntax:
seti $a=1
```

--------------------------------

### Capture user input

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Pauses execution to wait for keyboard input, storing the result in the specified variable.

```Bash
echo "What would you like to do?"
echo "1) Perform action 1"
echo "2) Perform action 2"
echo "3) Perform action 3"
echo "Enter your choice:
userinput $choicestring

# Extract the first number from the string
seti $choice = $choicestring 0
if $choice = 1
  echo "Your choice was 1"
elseif $choice = 2
  echo "Your choice was 2"
elseif $choice = 3
  echo "Your choice was 3"
else
  echo "Invalid choice"
endif
```

--------------------------------

### Read File to Buffer

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Reads data from a specified file into the buffer. Requires filename, buffer offset, file offset, and size.

```bash
# Read file to buffer
readbuffer input.bin 0 0 512
```

--------------------------------

### Assign string variables with sets

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Concatenate strings and variables into a single string variable. Syntax follows the echo command pattern.

```Bash
seti $a = 1
seti $b = 2

# Set the value of string to "a=1 and b=2"
sets $string = "a=" $a " and b=" $b
```

--------------------------------

### getfilesize

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Retrieves the size of a file in bytes.

```APIDOC
## getfilesize

### Description
Get the size of a file. The size in bytes is returned in `$error_level`.

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name or path of the file.

### Response
- **$error_level** (integer) - File size in bytes or -1 if the file does not exist or an error occurs.
```

--------------------------------

### Sleep/Delay Operation

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Pauses script execution for a specified duration in microseconds using the `usleep` command. Useful for timing-sensitive operations.

```bash
# Sleep/delay operations
usleep 5000000  # Sleep for 5 seconds
```

--------------------------------

### Extract data from buffer using seti

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Read bytes, words, double words, or quad words from the buffer at a specific offset. Data is interpreted as little-endian.

```Bash
# Exctract byte 234 from the buffer
seti $number = buffer 234

# Extract double word from the buffer starting at byte 234
seti $number = buffer 234 dw
```

--------------------------------

### Conditional Logic

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Implements control flow using if-else blocks. Nested if statements and string/number comparisons are supported.

```Bash
seti $high = 100

if $a > 1
  echo "a is greater than 1"
  if $a > 10
    echo "a is greater than 10"
    if $a > $high
      echo "a is greater than" $high
    endif
  endif
endif
```

```Bash
if $a > 0
  echo "a is greater than 0"
else
  echo "a is less than or equal to 0"
endif
```

--------------------------------

### Read File to Buffer

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Reads data from a file into the buffer at a specified offset.

```Bash
# Read the first 512 bytes of image.bin to the start of the buffer
readbuffer image.bin 0 0 512

# Read the second 512 bytes of image.bin to the buffer
readbuffer image.bin 0 512 512
```

--------------------------------

### Retrieve file size

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Returns the size of a file in bytes via $error_level, or -1 if the file is missing or inaccessible.

```Bash
# Get the size of "test.txt"
getfilesize test.txt

if $error_level = -1
  echo "File not found"
endif
```

--------------------------------

### Delete a file

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Removes a file from the filesystem. Filenames with spaces must be enclosed in a string.

```Bash
# Delete test.txt
deletefile test.txt
```

--------------------------------

### Parse Drive Information from Buffer

Source: https://context7.com/ispillmydrink/opensuperclone/llms.txt

Extracts model and serial number from the buffer after an ATA Identify Device command. Uses `buffer` with offsets and lengths.

```bash
# Parse and display drive information
wordflipbuffer 0 512
sets $model = buffer 54 40
echo "Model: " $model
sets $serial = buffer 20 20
echo "Serial: " $serial
```

--------------------------------

### ATA Command Operations

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Commands for preparing and executing ATA read/write operations and sending 28-bit or 48-bit commands.

```APIDOC
## setwritepio
### Description
Prepare for PIO write. Required before performing this type of ATA command. If the buffer size is set to zero prior to this command, it sets up for a non-data command.

## setreaddma
### Description
Prepare for DMA read. Required before performing this type of ATA command.

## setwritedma
### Description
Prepare for DMA write. Required before performing this type of ATA command.

## ata28cmd
### Description
Executes an ATA 28-bit command.
### Parameters
- **b0-b6** (bytes) - Required - Command bytes according to ATA documentation.

## ata48cmd
### Description
Executes an ATA 48-bit command.
### Parameters
- **w0-w4** (words) - Required - Command words.
- **b5-b6** (bytes) - Required - Device and command bytes.
```

--------------------------------

### Check variable type and source

Source: https://github.com/ispillmydrink/opensuperclone/wiki/Script-Reference

Uses variablecheck to determine if a variable is set and its origin (script vs command line). The result is stored in $error_level.

```Bash
# Check variable type for $input
variablecheck $input
if $error_level = 0
  echo "Variable not set"
elseif $error_level = 1
  echo "Variable is number but not set on command line"
elseif $error_level = 2
  echo "Variable is string but not set on command line"
elseif $error_level = 17
  echo "Variable is number and was set on command line"
elseif $error_level = 18
  echo "Variable is string and was set on command line"
endif
```