4 releases
0.2.1 | Jun 13, 2024 |
---|---|
0.2.0 | Jun 5, 2024 |
0.1.1 | Feb 23, 2024 |
0.1.0 | Feb 23, 2024 |
#234 in Hardware support
145KB
3.5K
SLoC
Scope is a multi-platform serial monitor with user-extensible features.
Key Features • Scope vs Other • Installation • How to Use • Project Goals
Send Data
With Scope
, you can type a message on the command bar (at bottom) and hit Enter
to send it through the serial port.
Send in Hexadecimal
You also can send bytes in hexadecimal. To do it, type $
and write your bytes in a hexadecimal format. The message
can have spaces and commas as separators (Scope
will send the bytes of message without spaces and commas).
Send Commands
You can send commands using the command bar. To send a command, type /
and a list of all available commands is
shown above the command bar. Continue typing the command and hit Enter
to send the command.
The commands are loaded from a user YAML file, passed at start of program (using -c
flag). An example of YAML file is
shown below:
hello: 'world!'
spaces: 'a big frase with spaces'
double_quotes: '"double"'
single_quotes: "'single'"
json: '{"cmd":1, "args":[true, "hello", 2.1]}'
json_again: '{"cmd":2, "args":"world"}'
Written History
It's possible to retrieve old data and commands sent. You can hit Up Arrow
and Down Arrow
to navigate through
the history of sent data and commands.
Auto Reconnect
The Scope
tool has an auto-reconnect feature. When the serial port isn't available, Scope
will keep trying to
reconnect to the serial port until it's available again.
Colorful
Scope
colors the command bar to notify the status of the serial connection: red to disconnected and green to
connected. Beyond status, the content read and written are colored too. The messages read is colored using ANSI terminal
color standard.
The data sent to serial port always has a background to differentiate it from read data. Characters outside the
printable range of the ASCII table are shown in magenta and in the hexadecimal format. Some characters are printed as
its representation, such as: \n
, \r
and \0
.
Setup Serial Port
It's possible change serial port and its baudrate while the tool is open. To do that,
type !serial connect COM4 9600
to set serial port to COM4
and baudrate to 9600
. You can also omit port to change
only the baudrate (!serial connect 9600
) or omit the baudrate to change only the port (!serial connect COM4
). If you
want to release the serial port, you'll type !serial disconnect
.
Save history
To save the all messages captured (and sent) since the start, you can hit Ctrl+s
. The history box will blink and a
message will be displayed on history. The filename is shown at top of history box with .txt
extension. There is, at
the history's top-right corner, the size of all message captured.
However, if you want to save only the message captured from now, you'll use the record feature. Hitting Ctrl+r
, you'll
start a record session. While in a record session, the history block is yellow and the Scope
will store all messages
captured from now. To stop the record session, you need to hit Ctrl+r
again. The right-corner indicator will show the
size of the record session. A new filename is created each time a new record session is started. Both: start session and
stop session, prints a message on the history box to indicate when it occurs.
Message Timestamp
All the data written or read has a gray timestamp on the left of the message and with the following
format: HH:MM:SS.ms
.
Multiplatform
You can use Scope
on multiple platforms, like: Linux, Windows and macOS[^1].
[^1]: Not tested yet.
History Navigation
You can navigate through the message history using the mouse wheel or hitting PageUp
and PageDown
.
Plugins
You can extend the basic functions of Scope
using plugins! Plugins are scripts written in lua
language. To create a
plugin for Scope
you'll need to write a lua script with these 2 functions: serial_rx
and user_command
.
The serial_rx
function is called when a new data is captured on serial port. The user_command
function is called
when you call your plugin from command bar, passing arguments to this command. The code bellow is a plugin to
reply OK\r\n
when receive the AT\r\n
message and to send Hello, World\r\n
when the user type !echo hello
on the
command bar.
require "scope"
function serial_rx(msg)
msg_str = bytes2str(msg)
if msg_str ~= "AT\r\n" then
return
end
scope.println("Sending msg \"OK\" via serial tx...")
scope.serial_tx(str2bytes("OK\r\n"))
scope.println("Message sent!")
end
function user_command(arg_list)
if arg_list[1] ~= "hello" then
return
end
scope.println("Hello, World!\r\n")
end
To call your plugin you need to type !
followed by your plugin name and a list of arguments. Inside your plugin, is
possible to do many action to interact with Scope
and serial port, such as: connect to a serial port, disconnect from
the serial port, send data to serial port, print some message in Scope
text view and so on. For more information about
the development of plugins for Scope
you can read
the Plugins Developer Guide.
Scope vs Others
The Scope
combine multiple features. The table below list these features:
Features | Scope (Free) | Docklight | Arduino | Tera Term | screen | esp-idf |
---|---|---|---|---|---|---|
Send Data | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Send in Hexadecimal | ✅ | ✅ | x | x | x | x |
Send Commands | ✅ | ✅ | x | x | x | x |
Written History | ✅ | ✅[^2] | x | x | x | x |
Auto Reconnect | ✅ | ✅ | x | ✅ | x | x |
Colorful | ✅ | x | x | ✅ | ✅ | ✅ |
Message Timestamp | ✅ | ✅ | x | x | x | x |
Display non-printable chars | ✅ | ✅ | x | x | x | x |
Multiplatform | ✅[^3] | Windows | ✅ | Windows | Linux | ✅ |
Interface | TUI | GUI | GUI | GUI | Terminal | Terminal |
Price | Free | €69 | Free | Free | Free | Free |
[^2]: The Docklight has a list of commands in lateral panel, so it doesn't need a command history
[^3]: Not tested on macOS yet
Installation
You can use cargo
to install Scope
or download a pre-built binary
at Releases page
Using cargo
cargo install scope-monitor
How to Use
After the installation, type scope serial
followed by the serial port and the desired baud rate. For example, to open
the port COM3
at 115200 bps
type:
scope serial COM3 115200
When the command bar at the bottom is green, it starts to capture messages from serial port and allows for sending messages.
To load a list of commands, from a YAML file, use should use -c <YOUR_COMMANDS>.yml
or --cmd-file <YOUR_COMMANDS>.yml
between scope
and serial
. For example, to load cmd.yml
file, use can type:
scope -c cmd.yml serial COM3 115200
or
scope --cmd-file cmd.yml serial COM3 115200
Project Goals
This project has 5 pillars that will direct the development of this tool:
I. Intuitive Usage: The usage of the tool must be intuitive. This means the usability should follow other popular
tool's common behaviours. For example, the history navigation (Up Arrow
and Down Arrow
) follows the history
navigation of OS terminal like in the Unix shell and in the Windows Powershell.
II. Compactness and Orthogonality: The features must follow
the compactness and orthogonality principles of the Unix.
III. User Centric Development: The development of this tool must deliver value to user in the first place,
instead of pleasing the developers. For example: the script language used to extend the tool must be a consolidated
programming language, instead of creating a new language. Another example is to prioritize critical bugs reported by
users, instead of launch new features.
IV. Multiplatform: All releases must work in Windows, Linux (zsh, shell and fish) and macOS.
V. Extensible: Support user scripts to extend base functionalities. These scripts are called plugins. For
more information about plugins
see Plugins Developer Guide
The roadmap, with next releases, may be found in GitHub project of this tool.
Community
For new feature requests and to report a bug, feel free to post a new issues on GitHub.
Contributing
Take a look at the CONTRIBUTING guide
Maintainers
Acknowledges
- Emilio Bottoni and José Gomes for the ideas that pushes forward this tool, for the tests that finds hidden bugs and for good features implementations.
License
Scope is made available under the terms of BSD v3 Licence.
See the LICENCE for license details.
Dependencies
~17–48MB
~761K SLoC