Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
8a9194383This file is pinned to the selected release. Download the original to open it in your design tool.
\documentclass[a4paper,11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc} % LY1 also works
\usepackage[margin=1in]{geometry}
%% Font settings suggested by fbb documentation.
\usepackage{textcomp} % to get the right copyright, etc.
\usepackage[lining,tabular]{fbb} % so math uses tabular lining figures
\usepackage[scaled=.95,type1]{cabin} % sans serif in style of Gill Sans
\usepackage[varqu,varl]{zi4}% inconsolata typewriter
\useosf % change normal text to use proportional oldstyle figures
%\usetosf would provide tabular oldstyle figures in text
\usepackage{svg}
\usepackage{enumitem}
\usepackage{longtable}
\setitemize{noitemsep,topsep=0pt,parsep=0pt,partopsep=0pt}
\setlist{leftmargin=*}
\usepackage{listings}
\definecolor{darkgreen}{RGB}{0,140,0}
\lstset{
basicstyle=\ttfamily,
frame=single,
breaklines=true,
morecomment=[l][\color{darkgreen}]{\#},
}
\lstnewenvironment{example}{\lstset{
,frame=single
,xleftmargin=2em
,xrightmargin=2em
% ,backgroundcolor=\color{lightgray}
,title=Example
}}{}
\usepackage{makecell}
\usepackage{hyperref}
\newcommand{\dev}{LibreCAL}
\newcommand{\gui}{\dev{}-GUI}
\newcommand{\screenshot}[2]{\begin{center}
\includegraphics[width=#1\textwidth]{Screenshots/#2}
\end{center}}
\newcommand{\event}[3]{
\noindent\textbf{Event:}
\begin{longtable}{p{.15\textwidth} | p{.80\textwidth} }
\hline
\textbf{Effect:} & #1 \\ \hline
\textbf{Syntax:} & #2 \\ \hline
\textbf{Parameters:} & \makecell[Xl]{#3} \\ \hline
\end{longtable}
}
\newcommand{\query}[4]{
\noindent\textbf{Query:}
\begin{longtable}{p{.15\textwidth} | p{.80\textwidth} }
\hline
\textbf{Effect:} & #1 \\ \hline
\textbf{Syntax:} & #2 \\ \hline
\textbf{Parameters:} & \makecell[tl]{#3} \\ \hline
\textbf{Return value:} & \makecell[tl]{#4} \\ \hline
\end{longtable}
}
\title{\dev{} SCPI Programming Guide}
\begin{document}
\maketitle
\setcounter{tocdepth}{3}
\tableofcontents
\clearpage
\section{Introduction}
The \dev{} firmware contains its own SCPI parser. The \gui{} is not necessary to use the SCPI commands.
There are two ways to send SCPI commands:
\begin{itemize}
\item \textbf{Virtual COM Port (VCP):} The \dev{} implements a VCP over which SCPI commands can be received.
\item \textbf{Custom USB interface:} The \dev{} implements a custom USB interface over which SCPI commands can be received.
\end{itemize}
Only one of these options should be used at a time. The advantage of the VCP is ease of use (any terminal will work), while the custom interface provides easier device identification (no need to manually assign COM ports) and is used by the \gui{}.
\section{General Syntax}
The syntax follows most SCPI rules:
\begin{itemize}
\item Arguments are case \textbf{sensitive}. While non-standard, this allows for more flexibility when naming coefficients. The command is still case \textbf{insensitive}.
\item The command tree is organized in branches, separated by a colon:
\begin{lstlisting}
:TEMPerature:STABLE?
\end{lstlisting}
\item Branches and commands can be abbreviated by using only the uppercase part of their name, the following commands are identical:
\begin{lstlisting}
:HEATer:POWer?
:HEAT:POW?
\end{lstlisting}
\item Every command generates a (possibly empty) response, terminated with a newline character.
\item Some commands require additional arguments that have to be passed after the command (separated by spaces):
\begin{lstlisting}
:TEMPerature 35
\end{lstlisting}
\item Two types of commands are available:
\begin{itemize}
\item \textbf{Events} change a setting or trigger an action. They usually have an empty response (unless there was an error).
\item \textbf{Queries} request information. They end with a question mark.
\end{itemize}
Some commands are both events and queries, depending on whether the question mark is present:
\begin{lstlisting}
:PORT? 1 # Returns the currently used standard at port 1
:PORT 1 OPEN # Configures port 1 to use the OPEN standard
\end{lstlisting}
\item Multiple commands per line (separated by a semicolon) are \textbf{not} supported.
\end{itemize}
\section{Commands}
\subsection{General Commands}
\subsubsection{*IDN}
\query{Returns the identifications string}{*IDN?}{None}{LibreCAL,LibreCAL,<serial>,<firmware\_version>}
\subsubsection{*LST}
\query{Lists all available commands}{*LST?}{None}{List of commands, separated by newline}
\subsubsection{:FIRMWARE}
\query{Returns the firmware version}{:FIRMWARE?}{None}{<major>.<minor>.<patch>}
\subsubsection{:BOOTloader}
\event{Reboots and enters the bootloader mode}{:BOOTloader}{None}
This is equivalent to pressing the "BOOTSEL" button when applying power.
\subsubsection{:DATE\_TIME}
\event{Sets local Date Time with UTC offset}{:DATE\_TIME <DATE> <TIME> <UTC>}{<DATE>Format YYYY/MM/DD\\<TIME>Format hh:mm:ss\\<UTC>Format UTC+/-hh:mm}
\query{Returns the local Date Time with UTC offset}{:DATE\_TIME?}{NONE}{local Date Time with UTC offset}
Example: Date Time with UTC offset(France):
\begin{lstlisting}
2023/03/20 17:06:58 UTC+01:00
\end{lstlisting}
\subsection{Port Control Commands}
This section contains commands to control and check the configuration of the ports.
\subsubsection{:PORTS}
\query{Returns the number of available ports}{:PORTS?}{None}{Number of ports, usually 4}
\subsubsection{:PORT}
\event{Set a port standard}{:PORT <port> <standard> [<dest>]}{<port> Port number, 1-4\\<standard> Selected standard, one of:\\OPEN\\SHORT\\LOAD\\THROUGH\\NONE\\<dest> Destination port of other the end, 1-4 (only required for THROUGH)\\}
When a port is set to through, <dest> is automatically also set to through (with <port> as its <dest>). Setting a port that is currently set to through to any other standard, sets the <dest> of that port to NONE.
Example:
\begin{lstlisting}
# Sets port 1 to LOAD standard
:PORT 1 LOAD
# Creates a through between port 2 and 3. This configures both ports
# as THROUGH with each other as the destination ports
:PORT 2 THROUGH 3
# Returns "THROUGH 2" because port 3 was also configured by the
# previous command
:PORT? 3
# Sets port 2 to SHORT standard. Because it was previously
# configured as THROUGH to port 3, port 3 will be set to NONE
:PORT 2 SHORT
# Returns "NONE"
:PORT? 3
\end{lstlisting}
\query{Returns the currently used standard at a port}{:PORT? <port>}{<port> Port number}{Standard, one of:\\OPEN\\SHORT\\LOAD\\THROUGH <dest>\\NONE}
\subsection{Temperature Control Commands}
This section contains commands related to the temperature regulation of the \dev{}. While it is possible to change the target temperature, this is not recommended as calibration coefficients will no longer be accurate due to temperature drift.
\subsubsection{:TEMPerature}
\event{Sets the target temperature}{:TEMPerature <temp>}{<temp> Target temperature in celsius}
\query{Returns the measured temperature}{:TEMPerature?}{NONE}{float value, current temperature in celsius}
\subsubsection{:TEMPerature:STABLE}
\query{Checks whether the target temperature has been reached}{:TEMPerature:STABLE?}{NONE}{TRUE or FALSE}
\subsubsection{:HEATer:POWer}
\query{Returns the currently used power by the heater}{:HEATer:POWer?}{NONE}{float value, heater power in watt}
\subsection{Coefficient Commands}
This section containg commands related to reading, creating and deleting calibration coefficients.
Some definitions:
\begin{itemize}
\item \textbf{Coefficient data:} S parameters for a specific standard at a given port and selected frequency. It consists of one complex value for reflection standards (open, short, load) and four complex values for transmission standards (through).
\item \textbf{Coefficient:} A list of coefficient data, containing multiple points over a frequency range. Each coefficient within a coefficient set is identified by its coefficient name. This name can be any of the following:
\begin{itemize}
\item P1\_OPEN
\item P1\_SHORT
\item P1\_LOAD
\item P2\_OPEN
\item P2\_SHORT
\item P2\_LOAD
\item P3\_OPEN
\item P3\_SHORT
\item P3\_LOAD
\item P4\_OPEN
\item P4\_SHORT
\item P4\_LOAD
\item P12\_THROUGH
\item P13\_THROUGH
\item P14\_THROUGH
\item P23\_THROUGH
\item P24\_THROUGH
\item P34\_THROUGH
\end{itemize}
\item \textbf{Coefficient set:} A named set of coefficients, contains all the different coefficients that are required to cover every port setting. The coefficient set is identified by its set name.
\end{itemize}
\subsubsection{:COEFFicient:LIST}
\query{Returns the names of all available coefficient sets}{:COEFFicient:LIST?}{NONE}{comma-separated list of coefficient set names}
\subsubsection{:COEFFicient:DELete}
\event{Deletes a calibration coefficient}{:COEFFicient:DELete <set name> <coefficient name>}{<set name> Name of the coefficient set\\<coefficient name> Name of the coefficient}
\subsubsection{:COEFFicient:NUMber}
\query{Returns the number of data points within a coefficient}{:COEFFicient:NUMber? <set name> <coefficient name>}{<set name> Name of the coefficient set\\<coefficient name> Name of the coefficient>}{Integer, number of data points in coefficient}
\subsubsection{:COEFFicient:GET}
\query{Returns coefficient data from a coefficient}{:COEFFicient:GET? <set name> <coefficient name> <index>}{<set name> Name of the coefficient set\\<coefficient name> Name of the coefficient>\\<index> Data point number}{comma-separated list of float values}
The first value returned is the frequency (in GHz), followed by the S parameters. Each S parameter is split into two float values, the first value is the real part, the second value the imaginary part. For reflection standards, only one S parameter is returned (S11). For transmission standards, four S parameters are returned in S11, S21, S12, S22 order.
\subsubsection{:COEFFicient:CREATE}
\event{Creates a new calibration coefficient}{:COEFFicient:CREATE <set name> <coefficient name>}{<set name> Name of the coefficient set\\<coefficient name> Name of the coefficient}
If the coefficient already exists, it will be deleted first (along with all its coefficient data). Afterwards, a new and empty coefficient will be created.
This command should be used in conjunction with :COEFFicient:ADD\_COMMENT, :COEFFicient:ADD and :COEFFicient:FINish.
\subsubsection{:COEFFicient:ADD\_COMMENT}
\event{Add ASCII text comment before to add coefficient datapoint}{:COEFFicient:ADD\_COMMENT <ASCII text comment>}{<ASCII text comment> add an ASCII text comment with size up to 120chars\\if the comment exceed 120 characters it will be truncated to 120 characters}
This command should be used only after :COEFFicient:CREATE as it is intended to add comment before to add any datapoint (:COEFFicient:ADD).
There is a limitation of maximum 100 comments per calibration coefficient (:COEFFicient:CREATE)(if there is more comment the command will return an error and comment will be not added).
\subsubsection{:COEFFicient:ADD}
\event{Add a datapoint to an existing coefficient}{:COEFFicient:ADD <frequency> <S parameters>}{<frequency> Frequency of the datapoint, in GHz\\
<S parameters> S parameters, split into real and imaginary parts}
This command should be used in conjunction with :COEFFicient:CREATE and :COEFFicient:FINish. It must only be used after a coefficient has been created using :COEFFicient:CREATE and before the coefficient has been completed by :COEFFicient:FINish.
The order of values in the S parameter argument is the same as for the :COEFFicient:GET command, except that values are separated by spaces instead of a comma. Reflection standard require one S parameter (two arguments), transmission standards require four S parameters (eight arguments).
\subsubsection{:COEFFicient:FINish}
\event{Completes the creation of a coefficient}{:COEFFicient:FINish}{None}
This command should be used in conjunction with :COEFFicient:CREATE and :COEFFicient:Add. It must be used after all data has been added to the coefficient.
\subsubsection{:FACTory:ENABLEWRITE}
The default coefficient set ("FACTORY") is read-only to prevent accidentally overwriting or deleting these important coefficients. Unless you are building your own \dev{}, you should never change these coefficients!
This command makes all coefficient sets writable. DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING!
Once issued, the default coefficient set stays writable until the next reboot.
\event{Make all coefficient sets writable}{:FACTory:ENABLEWRITE <key>}{<key> Prevents accidental usage, set to "I\_AM\_SURE"}
\end{document}