### Example Protocol File

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

This example demonstrates the basic structure of a Stream Device protocol file, including defining terminators, commands with input/output specifications, and initialization routines.

```protocol
# This is an example protocol file

Terminator = CR LF;

# Frequency is a float
# use ai and ao records

getFrequency {
    out "FREQ?"; in "%f";
}

setFrequency {
    out "FREQ %f";
    @init { getFrequency; }
}

# Switch is an enum, either OFF or ON
# use bi and bo records

getSwitch {
    out "SW?"; in "SW %{OFF|ON}";
}

setSwitch {
    out "SW %{OFF|ON}";
    @init { getSwitch; }
}

# Connect a stringout record to this to get
# a generic command interface.
# After processing finishes, the record contains the reply.

debug {
    ExtraInput = Ignore;
    out "%s"; in "%39c"
}


```

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

### Protocol Example with Arguments

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

This example demonstrates how to define and use a protocol with arguments for output operations. The argument is used in the output string formatting.

```text
moveaxis {
 out "move$1 %.6f";
}
field (OUT, "@motor.proto moveaxis(X) motor1")
```

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

### Protocol Definition for Example Record

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

The 'read' protocol definition corresponding to the 'ai' record example, showing how arguments are parsed and used.

```streamdevice
read { out 0x8$1 "READ $2"; in "%f,%(\$3recY\$1)f" }
```

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

### Protocol Example with Input Arguments

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

This example shows how to use arguments in a protocol for input operations. The argument is passed to the protocol and used in the input command and format string.

```text
readpressure {
 out 0x02 0x00 $1;
 in 0x82 0x00 $1 "%2r";
}
field (INP, "@vacuumgauge.proto readpressure(0x84) gauge3")
```

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

### StreamDevice Protocol for Getting ROI Start Value

Source: https://paulscherrerinstitute.github.io/StreamDevice/processing.html

Defines the StreamDevice protocol for the 'getROIstart' function. It sends a request 'ROI?' to the device and expects a reply starting with 'ROI ' followed by two floating-point numbers, capturing the first one.

```StreamDevice Protocol
getROIstart {
    out "ROI?";
    in  "ROI %f %*f";
}
```

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

### Format String Parsing Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/formatconverter.html

Illustrates how the 'source' pointer is advanced after parsing a format string, showing the state before and after the parse() call.

```text
 source       source
 before       after
 parse()      parse()
     |
"%39[0-9a-zA-Z]constant text"
    |
 conversion
 character
```

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

### Configure VXI11 (GPIB over TCP/IP) for StreamDevice

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Example startup script configuration for a VXI11 device. Sets the StreamDevice protocol path and configures the VXI11 connection with IP address, host, and device parameters.

```shell
epicsEnvSet ("STREAM_PROTOCOL_PATH", ".:../protocols")

vxi11Configure ("PS1","192.168.164.10",1,1000,"hpib")

```

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

### Configure TCP/IP Port for StreamDevice

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Example startup script configuration for a TCP/IP connection. Sets the StreamDevice protocol path and configures the asyn IP port with a specified address and port.

```shell
epicsEnvSet ("STREAM_PROTOCOL_PATH", ".:../protocols")

drvAsynIPPortConfigure ("PS1", "192.168.164.10:23")

```

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

### Configure Serial Port for StreamDevice

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Example startup script configuration for a serial device. Sets the StreamDevice protocol path and configures the asyn serial port with specific options.

```shell
epicsEnvSet ("STREAM_PROTOCOL_PATH", ".:../protocols")

drvAsynSerialPortConfigure ("PS1","/dev/ttyS1")
asynSetOption ("PS1", 0, "baud", "9600")
asynSetOption ("PS1", 0, "bits", "8")
asynSetOption ("PS1", 0, "parity", "none")
asynSetOption ("PS1", 0, "stop", "1")
asynSetOption ("PS1", 0, "clocal", "Y")
asynSetOption ("PS1", 0, "crtscts", "N")

```

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

### StreamDevice Record with Protocol Arguments

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

An example of an 'ai' record using the 'stream' DTYP, demonstrating complex protocol argument passing including macros and special characters.

```epics
record(ai, "$(PREFIX)recX5") {
    field(DTYP, "stream")
    field(INP,  "@$(PROTOCOLFILE) read(5, X\,Y $(PREFIX)) $(PORT)")
}
record(ai, "$(PREFIX)recY5") {}
```

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

### String Concatenation Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Illustrates how a single string can be constructed from multiple quoted literals and byte values, separated by whitespace or commas.

```StreamDevice Protocol
"Hello world\r\n"
```

```StreamDevice Protocol
'Hello',0x20,"world",CR,LF
```

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

### scalcout Record CALC Expression Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/scalcout.html

Example of a minimal valid CALC expression for scalcout records, ensuring OVAL is calculated.

```text
"0"
```

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

### Configure ASYN Driver Path

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Adds the path to the asynDriver installation to the `configure/RELEASE` file. This enables StreamDevice to communicate with hardware via the asynDriver.

```makefile
ASYN=/home/epics/asyn4-45
```

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

### Example of @init Exception Handler

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

This snippet shows how to use the @init exception handler to initialize an output record by reading a value from the device. It is called when an exception occurs, allowing for a clean reset or initialization.

```streamdevice
setPosition {
    out "POS %f";
    @init { out "POS?"; in "POS %f"; }
}    

```

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

### AI Record Configuration for ROI Start

Source: https://paulscherrerinstitute.github.io/StreamDevice/processing.html

Configures an AI record to process the start value of a Region of Interest (ROI) from a device. It uses a StreamDevice input process file and specifies the device to communicate with.

```EPICS
record (ai "ROI:start") {
    field (DTYP, "stream")
    field (INP,  "@myDev.proto getROIstart dev1")
}
```

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

### Configure EPICS_BASE Path

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Specifies the installation location of the EPICS base directory in the `configure/RELEASE` file. This is essential for the build process.

```makefile
EPICS_BASE=/home/epics/base-7.0.9
```

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

### Handle Multi-line Messages

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

Use multiple 'in' commands for each line of input when a device sends multi-line messages. This example shows how to read a two-line message.

```Device Support
read_value {
in "Here is the value:";
in "%f";
}
```

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

### Example Protocol Definition for Power Supply

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Defines 'getCurent' and 'setCurrent' protocols for a power supply device. The 'setCurrent' protocol includes an '@init' handler to call 'getCurent' during initialization. Assumes CR LF terminator.

```proto
Terminator = CR LF;

getCurent {
        out "CURRENT?";
        in "CURRENT %f A";
    }

setCurrent {
    out "CURRENT %.2f";
    @init {
        getCurent;
    }

}

```

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

### Configure CALC Module Path

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Specifies the installation path for the EPICS calc module in the `configure/RELEASE` file. This is required if StreamDevice needs support for the sCalcout record.

```makefile
CALC=/home/epics/synApps/calc-R3-7-5
```

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

### StreamDevice Protocol for Getting ROI End Value

Source: https://paulscherrerinstitute.github.io/StreamDevice/processing.html

Defines the StreamDevice protocol for the 'getROIend' function. It expects a reply starting with 'ROI ' and captures the second floating-point number, ignoring the first one using '%*f'. This protocol is designed to work with I/O Intr mode.

```StreamDevice Protocol
getROIend {
    in  "ROI %*f %f";
}
```

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

### Get Client Name

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Retrieves the name of the client instance associated with this bus interface. Useful for logging and error messages.

```cpp
const char* clientName();
```

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

### aao Record STRING Input Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Inputs array elements as strings when FTVL is STRING. Each input string is assigned to an array element.

```text
_Input:_ `VAL[i]=_x[i]_`
```

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

### aao Record STRING Output Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Outputs array elements as strings when FTVL is STRING. Each element is treated as a separate string.

```text
_Output:_ `_x[i]_=VAL[i]`
```

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

### Accessing scalcout Record Fields

Source: https://paulscherrerinstitute.github.io/StreamDevice/scalcout.html

Example of accessing fields A-L and AA-LL directly in scalcout records using format specifiers.

```text
"%(A)f"
```

```text
"%(BB)s"
```

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

### LONG Converter Registration Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/formatconverter.html

This C++ code demonstrates how to define and register a custom converter class for handling long integers with the conversion character '%Q'. It shows the necessary includes, class definition with parse, printLong, and scanLong methods, and the RegisterConverter call.

```cpp
#include "StreamFormatConverter.h"

class MyConverter : public StreamFormatConverter
{
    int parse(const StreamFormat&, StreamBuffer&, const char*&, bool);
    bool printLong(const StreamFormat&, StreamBuffer&, long);
    ssize_t scanLong(const StreamFormat&, const char*, long&);
};

RegisterConverter(MyConverter,"Q");

// ... (implementation)

```

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

### aao Record DOUBLE Input Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Inputs array elements as doubles, converting from the specified FTVL. FTVL must be FLOAT or DOUBLE.

```text
_Input:_ `VAL[i]=FTVL(_x[i]_)`
```

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

### aao Record CHAR/UCHAR Output Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Outputs the complete aao as a single string of size NORD when FTVL is CHAR or UCHAR. The first NORD characters are printed.

```text
_Output:_ `_x_=range(VAL,0,NORD)`
```

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

### Example Bus Interface Class Declaration

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

This C++ code declares a custom bus interface class 'MyInterface' that inherits from 'StreamBusInterface'. It includes the necessary virtual methods to be implemented and a static creator method. The class is registered using 'RegisterStreamBusInterface'.

```cpp
#include <StreamBusInterface.h>

class MyInterface : StreamBusInterface
{
    // ... (internally used attributes and methods)

    MyInterface(Client* client);
    ~MyInterface();

    // StreamBusInterface virtual methods
    bool lockRequest(unsigned long lockTimeout_ms);
    bool unlock();
    bool writeRequest(const void* output, size_t size, unsigned long writeTimeout_ms);
    bool readRequest(unsigned long replyTimeout_ms, unsigned long readTimeout_ms, ssize_t expectedLength, bool async);
    bool supportsAsyncRead();
    bool supportsEvent();
    bool acceptEvent(unsigned long mask, unsigned long timeout_ms);
    bool connectRequest(unsigned long timeout_ms);
    bool disconnectRequest();
    void finish();

public:
    // creator method
    static StreamBusInterface* getBusInterface(
        Client* client, const char* busname,
        int addr, const char* param);
};

RegisterStreamBusInterface(MyInterface);

// ... (implementation)

```

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

### Handle Mixed Data Types with @mismatch

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

Use the @mismatch exception handler and redirection to records when a device sends mixed data types. This example shows how to read a current value, handling both numeric and string responses.

```StreamDevice
read_current {
  out "CURRENT?"
  in "CURRENT %f A"
  @mismatch {
    in "%(\39c)"
  }
}
```

```StreamDevice
record (ai, "$(DEVICE):readcurrent") {
  field (DTYP, "stream")
  field (INP, "@$(DEVICETYPE).proto read_current($(DEVICE):message) $(BUS)")
}
record (stringin, "$(DEVICE):message") {
}
```

```StreamDevice
record (calcout, "$(DEVICE):clean_1") {
  field (INPA, "$(DEVICE):readcurrent.SEVR CP")
  field (CALC, "A#3")
  field (OOPT, "When Non-zero")
  field (OUT,  "$(DEVICE):clean_2.PROC")
}
record (stringout, "$(DEVICE):clean_2") {
  field (VAL, "OK")
  field (OUT,  "$(DEVICE):message PP")
}
```

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

### Get Bus Interface Instance

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Static method to retrieve a bus interface instance for a given client and bus name. It checks if the interface class is responsible for the bus and if the address is valid. Returns a pointer to the interface on success, or NULL on failure.

```cpp
static StreamBusInterface* getBusInterface(Client* client, const char* busname, int addr, const char* param);
```

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

### Read Web Page Title with Regular Expressions

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

Read the title of a web page by sending a GET request and using a regular expression to extract the content between the <title> tags. Ensure a sufficient reply timeout and handle potential case variations.

```StreamDevice
get_title {
  extrainput = ignore;
  replyTimeout = 1000;
  out "GET http://$1\r\n\r\n";
  in "%+.1/(?im)<title>(.*)<\/title>/";
}
```

```StreamDevice
record (stringin, "$(DEVICE):title") {
  field (DTYP, "stream")
  field (INP,  "@$(DEVICETYPE).proto get_title($(PAGE)) $(BUS)")
}
record (waveform, "$(DEVICE):longtitle") {
  field (DTYP, "stream")
  field (INP,  "@$(DEVICETYPE).proto get_title($(PAGE)) $(BUS)")
  field (FTVL, "CHAR")
  field (NELM, "100")
}
```

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

### Extracting HTML Title using Regex

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

This example demonstrates how to extract the content of an HTML title tag using a PCRE regular expression. It skips content before the opening tag and leaves content after the closing tag in the input buffer.

```StreamDevice
%/.1/<title>(.*)<\/title>/
```

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

### Get Output Terminator

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Retrieves any terminator bytes that have been added to the output by the client.

```cpp
const char* getOutTerminator(size_t& length);
```

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

### Get Lock Priority

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Returns the priority of the bus interface for lock queuing.

```cpp
long priority();
```

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

### Request Write Output

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Initiates writing data to a device. Returns true if accepted, false otherwise. Does not block until completion.

```cpp
bool writeRequest(const void* output, size_t size, unsigned long writeTimeout_ms);
```

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

### Get Input Terminator

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Retrieves any terminator bytes that the bus interface should expect at the end of input.

```cpp
const char* getInTerminator(size_t& length);
```

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

### mbbiDirect Record: LONG Format - With Mask

Source: https://paulscherrerinstitute.github.io/StreamDevice/mbbiDirect.html

For LONG format when MASK is not 0, output writes RVAL&MASK, and input reads _x_&MASK. MASK is initialized from NOBT.

```text
_Output:_ `_x_=RVAL&MASK`
_Input:_ `RVAL=_x_&MASK`
```

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

### Initialize StreamDevice record with input/output link

Source: https://paulscherrerinstitute.github.io/StreamDevice/recordinterface.html

Initializes a record by passing its I/O link to StreamDevice for parsing and registering read/write functions. Typically calls streamInitRecord.

```c
static long initRecord(dbCommon *record)
{
    recordtypeRecord *rec = (recordtypeRecord *)record;

    return streamInitRecord(record, &rec->out, readData, writeData);
}

```

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

### Basic Protocol Arguments for Motor Control

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Demonstrates how protocol arguments can differentiate similar protocols for motor axes X, Y, and Z.

```streamdevice
moveX { out "X GOTO %d"; }
moveY { out "Y GOTO %d"; }
moveZ { out "Z GOTO %d"; }
```

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

### Output EGU field of the active record

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Outputs the EGU field of the currently active record. This is a simple example of I/O redirection.

```StreamDevice Format
out "%(EGU)s";
```

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

### Input using protocol argument for record redirection

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Demonstrates using a protocol argument to specify a part of the record name for redirection. This is useful for avoiding full record names in protocol files.

```StreamDevice Format
in "%(\$1recordpart)f"
```

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

### Download StreamDevice Repository

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Clones the StreamDevice Git repository to your local machine. This is the primary step for obtaining the source code.

```git
git clone https://github.com/paulscherrerinstitute/StreamDevice.git
```

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

### Unified Protocol with Arguments

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Shows a single protocol definition using arguments to control different axes, reducing redundancy.

```streamdevice
move { out "$1 GOTO %d"; }
```

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

### Add StreamDevice Dependencies to Makefile

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Include these lines in your application's Makefile to link against the StreamDevice, asyn, and pcre libraries.

```makefile
PROD_LIBS += stream
PROD_LIBS += asyn
PROD_LIBS += pcre

```

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

### scalcout Record Initialization Fix

Source: https://paulscherrerinstitute.github.io/StreamDevice/scalcout.html

A required fix for the sCalcout.c file in versions up to synApps release 5.1 to ensure proper record initialization.

```c
        if(pscalcoutDSET->init_record ) {
            return (*pscalcoutDSET->init_record)(pcalc);
        }

```

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

### Request Read Input

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Initiates reading input from a device. Returns true if accepted, false otherwise. Does not block until input is available.

```cpp
bool readRequest(unsigned long replyTimeout_ms, unsigned long readTimeout_ms, ssize_t expectedLength, bool async);
```

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

### Include StreamDevice and Asyn DBDs in Application

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Add these lines to your application's xxxAppInclude.dbd file to enable StreamDevice and asyn support for serial, IP sockets, and VXI11.

```dbd
include "base.dbd"
include "stream.dbd"
include "asyn.dbd"
registrar(drvAsynIPPortRegisterCommands)
registrar(drvAsynSerialPortRegisterCommands)
registrar(vxi11RegisterCommands)

```

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

### Configure Input Record for StreamDevice

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Use this snippet to create an input record (ai) that reads data using StreamDevice. Ensure the DTYP field is set to 'stream' and the INP field specifies the protocol file, protocol name, and bus.

```EPICS
record (ai, "PS1:I-get")
{
    field (DESC, "Read current of PS1")
    field (DTYP, "stream")
    field (INP,  "@ExamplePS.proto getCurrent PS1")
    field (EGU,  "A")
    field (PREC, "2")
    field (LOPR, "0")
    field (HOPR, "60")
    field (PINI, "YES")
    field (SCAN, "10 second")
}
```

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

### aao Record LONG or ENUM Input Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Inputs array elements as long integers, converting from the specified FTVL. The value is truncated if FTVL has a smaller data size than long.

```text
_Input:_ `VAL[i]=FTVL(_x[i])_`
```

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

### aao Record CHAR/UCHAR Input Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Inputs a string into the aao record when FTVL is CHAR or UCHAR. A maximum of NELM-1 characters can be read, and NORD is updated to the index of the first trailing zero.

```text
_Input:_ `VAL=_x_, NORD=length(_x_)`
```

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

### Configure PCRE Include and Library Paths (Linux x86)

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Sets the include and library paths for the PCRE package on a Linux x86 system. This is necessary for enabling regular expression matching support in StreamDevice.

```makefile
PCRE_INCLUDE=/usr/include/pcre
PCRE_LIB=/usr/lib
```

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

### Configure PCRE Include and Library Paths (Linux x86 64-bit)

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Specifies the include and library paths for the PCRE package on a 64-bit Linux system. This is required for regular expression support.

```makefile
PCRE_INCLUDE=/usr/include/pcre
PCRE_LIB=/usr/lib64
```

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

### User Variables for Frequency Settings

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Illustrates the use of user variables to define shorthand for frequently used strings like 'FREQ' and format specifiers.

```streamdevice
f = "FREQ";     # sets f to "FREQ" (including the quotes)
f1 = $f " %f";  # sets f1 to "FREQ %f"
```

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

### Quoted String Literals

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Examples of string literals using single and double quotes. Quotes of the other type can be used within the string. Long strings can be broken across lines by closing and reopening quotes.

```StreamDevice Protocol
"That's a string."
```

```StreamDevice Protocol
'Say "Hello"'
```

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

### aao Record DOUBLE Output Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Outputs array elements as doubles, applying the format converter. FTVL can be DOUBLE, FLOAT, INT64, UINT64, LONG, ULONG, SHORT, USHORT, CHAR, UCHAR, or ENUM.

```text
_Output:_ `_x[i]_=double(VAL[i])`
```

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

### mbboDirect Record: MASK Initialization

Source: https://paulscherrerinstitute.github.io/StreamDevice/mbboDirect.html

Explains how the MASK field is initialized based on NOBT and SHFT values. The record then calculates RVAL based on the VAL field shifted.

```text
`MASK` is initialized to `NOBT` 1-bits shifted left by `SHFT` (`((2^NOBT)-1)<<SHFT`). The record calculates `RVAL=VAL<<SHFT`.
```

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

### Protocol Using User Variables for Frequency

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Demonstrates 'getFrequency' and 'setFrequency' protocols that utilize user-defined variables for cleaner syntax.

```streamdevice
getFrequency {
    out $f "?"; # same as: out "FREQ?"; 
    in $f1;     # same as: in "FREQ %f"; 
}

setFrequency {
    out $f1;    # same as: out "FREQ %f"; 
}
```

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

### mbbiDirect Record: LONG Format - No Mask

Source: https://paulscherrerinstitute.github.io/StreamDevice/mbbiDirect.html

For LONG format when MASK is 0 (NOBT not set), output writes the value to VAL, and input reads from VAL.

```text
_Output:_ `_x_=VAL`
_Input:_ `VAL=_x_`
```

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

### Set Variable Syntax

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Use this syntax to set a variable in a protocol file. Variables can be system or user-defined.

```protocol
_variable_ = _value_;
```

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

### Configure Output Record for StreamDevice

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Use this snippet to create an output record (ao) that writes data using StreamDevice. Set the DTYP field to 'stream' and the OUT field to specify the protocol file, protocol name, and bus.

```EPICS
record (ao, "PS1:I-set")
{
    field (DESC, "Set current of PS1")
    field (DTYP, "stream")
    field (OUT,  "@ExamplePS.proto setCurrent PS1")
    field (EGU,  "A")
    field (PREC, "2")
    field (DRVL, "0")
    field (DRVH, "60")
    field (LOPR, "0")
    field (HOPR, "60")
}
```

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

### aao Record LONG or ENUM Output Example

Source: https://paulscherrerinstitute.github.io/StreamDevice/aao.html

Outputs array elements as long integers, applying the format converter. FTVL can be INT64, UINT64, LONG, ULONG, SHORT, USHORT, CHAR, UCHAR, or ENUM. Signed values are sign-extended, unsigned values are zero-extended.

```text
_Output:_ `_x[i]_=long(VAL[i])`
```

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

### Configure Serial Port with Software Flow Control

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Configures the serial port to use software flow control (XON/XOFF) by setting 'ixon' and 'ixany' options to 'Y'.

```shell
asynSetOption ("PS1", 0, "ixon", "Y")
asynSetOption ("PS1", 0, "ixany", "Y")

```

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

### Write Values from Other Records using Redirection

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

Use redirection to records to write values from other records on the same IOC. Specify record names or record.FIELD directly after the '%' or use protocol arguments like '$1'.

```Device Support
acquire {out 'ACQUIRE "%(\1:directory)s/%s",%(\1:time).3f;';}
record (stringout, "$(DEVICE):getimage") {
  field (DTYP, "stream")
  field (OUT, "@$(DEVICETYPE).proto acquire($(DEVICE)) $(BUS)")
}
```

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

### Connection Callback

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Callback function to be called when the device has connected. Can be called asynchronously. Defaults to StreamIoSuccess.

```cpp
void connectCallback(IoStatus status = StreamIoSuccess);
```

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

### Using Protocol Arguments

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

Reference arguments passed to a protocol using $1, $2, etc. Arguments can be referenced directly or within strings by escaping them with a backslash.

```text
field (OUT, "@protocolfile protocol(arg1,arg2,arg3) bus")
In the protocol, reference arguments as $1 $2 $3 or inside strings as "\$1 \$2 \$3".
```

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

### StreamBusInterface Constructor

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Constructor for the StreamBusInterface. It should pass the client pointer to the base class constructor.

```cpp
StreamBusInterface(Client* client);
```

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

### Request Connection

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Requests a connection to the device with a specified timeout. Should not block but return immediately. Calls connectCallback upon successful connection or if connection fails within the timeout.

```cpp
bool connectRequest(unsigned long timeout_ms);
```

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

### Binary Converter with Default Characters

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Equivalent to %b, this format uses '0' and '1' to represent binary digits.

```StreamDevice Format
%B01
```

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

### Read Callback

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Called when input has been received. Returns the number of bytes expected or a negative value for unspecified amounts.

```cpp
ssize_t readCallback(IoStatus status, const void* buffer = NULL, size_t size = 0);
```

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

### Print String Method Signature

Source: https://paulscherrerinstitute.github.io/StreamDevice/formatconverter.html

Signature for printing a null-terminated string to a stream buffer.

```C++
bool printString(const StreamFormat& fmt, StreamBuffer& output, const char* value);
```

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

### System Variable: MaxInput

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Sets the maximum number of bytes to read before terminating input, used for devices without terminators. '0' means infinite.

```protocol
MaxInput = 0;
```

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

### Raw Converter for Unsigned Input with Width

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Reads bytes into an unsigned integer value. '%02r' reads 2 bytes and treats the value as unsigned.

```StreamDevice Format
in "%02r";
```

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

### Move Postfix Sign to Front

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Moves a postfix sign (like '+' or '-') to the front of a number. This is useful for standardizing the representation of signed numbers.

```streamdevice
%#/([^+-])*([+-])/\2\1/
```

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

### Check Event Support

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Implement this method to indicate if the bus interface supports event notifications. The default implementation returns false.

```cpp
bool supportsEvent();
```

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

### Compare input with formatted current value

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Compares the input against the current value formatted as a float with 3 decimal places. The format succeeds only if the input matches.

```StreamDevice
in "%=.3f";
```

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

### Configure Debug and Error Messages (iocsh)

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Sets various variables using iocsh commands to control debug and error message behavior. Enables debug and error messages, colored output, sets a dead time for repeated errors, enables timestamps, and redirects debug output to a log file.

```shell
var streamError 1
var streamDebug 1
var streamDebugColored 1
var streamErrorDeadTime 30
var streamMsgTimeStamped 1
streamSetLogfile("logfile.txt")

```

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

### System Variable: LockTimeout

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Configures the milliseconds to wait for exclusive device access before timing out. Affects the first 'out' command.

```protocol
LockTimeout = 5000;
```

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

### Configure PCRE Top Directory

Source: https://paulscherrerinstitute.github.io/StreamDevice/setup.html

Defines the top-level directory for the PCRE package in the StreamDevice `RELEASE` file. This is used when PCRE is built as an EPICS module.

```makefile
PCRE=/home/epics/pcre
```

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

### Print Pseudo Method Signature

Source: https://paulscherrerinstitute.github.io/StreamDevice/formatconverter.html

Signature for printing a pseudo-value to a stream buffer.

```C++
bool printPseudo(const StreamFormat& fmt, StreamBuffer& output);
```

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

### Read decimal number followed by a percent sign

Source: https://paulscherrerinstitute.github.io/StreamDevice/formats.html

Reads a decimal number and then expects a literal '%' character immediately following it.

```StreamDevice
in "%d%%";
```

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

### System Variable: ReplyTimeout

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Defines the milliseconds to wait for the first input byte from the device. Affects 'in' commands.

```protocol
ReplyTimeout = 1000;
```

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

### System Variable: WriteTimeout

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Sets the milliseconds to wait for output to be written after acquiring device access. Affects 'out' commands.

```protocol
WriteTimeout = 100;
```

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

### Finish Protocol

Source: https://paulscherrerinstitute.github.io/StreamDevice/businterface.html

Cleans up resources and cancels outstanding requests for a client after a protocol ends.

```cpp
void finish();
```

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

### System Variable: ExtraInput

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Determines how to handle extra input bytes after parsing is complete. Can be 'Error' or 'Ignore'. Affects 'in' commands.

```protocol
ExtraInput = Error;
```

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

### Escape Sequences in Strings

Source: https://paulscherrerinstitute.github.io/StreamDevice/protocol.html

Demonstrates various escape sequences available within quoted string literals for special characters and byte representations.

```StreamDevice Protocol
"\"\\'\%\\"
```

```StreamDevice Protocol
"\a\b\t\n\r\e"
```

```StreamDevice Protocol
"\x41\010\1"
```

```StreamDevice Protocol
"?"
```

```StreamDevice Protocol
"\_"
```

```StreamDevice Protocol
"\$variable_name"
```

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

### Write Multiple Numeric Values using Calcout Record

Source: https://paulscherrerinstitute.github.io/StreamDevice/tipsandtricks.html

Use a calcout record and redirection to fields to write up to 12 numeric values. Ensure a valid expression is specified in the CALC field, even if unused.

```Device Support
write_ABC {out "A=%(A).2f B=%(B).6f C=%(C).0f";}
record (calcout, "$(RECORD)") {
  field (INPA, "$(A_RECORD)")
  field (INPB, "$(B_RECORD)")
  field (INPC, "$(C_RECORD)")
  field (CALC, "0")
  field (DTYP, "stream")
  field (OUT, "@$(DEVICETYPE).proto write_ABC $(BUS)")
}
```

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

### scalcout Record STRING Input Format

Source: https://paulscherrerinstitute.github.io/StreamDevice/scalcout.html

Defines the input format for STRING type values in scalcout records. SVAL is used to read the string value.

```text
SVAL=_x_
```

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

### scalcout Record STRING Output Format

Source: https://paulscherrerinstitute.github.io/StreamDevice/scalcout.html

Defines the output format for STRING type values in scalcout records. OSV is used for the string value.

```text
_x_=OSV
```