Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode Skip to content
Cahute 0.6
Logo
Cahute 0.6
  • Installation guides
    • Installing Cahute on Linux distributions
    • Installing Cahute on macOS / OS X
    • Installing Cahute on Microsoft Windows
    • Installing Cahute on AmigaOS
  • Build from source guides
    • Building Cahute for Linux distributions
    • Building Cahute for macOS / OS X
    • Building Cahute for Microsoft Windows
    • Building Cahute for AmigaOS
  • Contribution guides
    • Contributing to Cahute
    • Reporting a bug or vulnerability
    • Requesting a feature
    • Packaging Cahute
    • Creating a merge request
  • Command line user guides
    • Getting information regarding a calculator
    • Sending a file to a calculator’s storage memory
    • Getting a file from the calculator’s storage memory
    • Displaying the screen from a calculator
  • Developer guides
    • Building with the Cahute library
    • Using device detection
      • Listing calculators connected by USB
      • Listing available serial ports
    • Using links
      • Opening a link to a calculator connected by USB
      • Opening a generic link to a calculator connected by serial
    • Reading and writing files
      • Guessing the type of a file
    • Using text conversion utilities
      • Converting text from an encoding to another
  • Miscellaneous guides
    • Getting started with Cahute in Visual Studio
    • Capturing USB communications on Windows using Wireshark
  • Data formats
    • Number formats
    • Picture formats
    • Text encodings
    • File formats
      • fx-CG add-ins
      • fx-9860G add-ins
      • Calculator Text Format (CTF)
      • CASIOLINK archives
      • casrc configuration file
      • Catalog files (CAT)
      • e-Activity files
      • fx-CG f-key files
      • fx-9860G f-key files
      • FX Program (FXP)
      • GraphCard file format
      • fx-CG language files
      • fx-9860G language files
      • Main memory archives
      • fx-CG picture
      • fx-CP picture
  • Communication protocols
    • Rationales behind the communication protocols
    • Transport medium and protocols
    • USB detection for CASIO calculators
    • CASIOLINK protocols – Serial protocols used by pre fx-9860G calculators
    • CAS40 protocol – Serial protocol used by pre-1996 calculators
      • CAS40 packet format
      • CAS40 data types
      • CAS40 flows
    • CAS50 protocol – Serial protocol used by calculators from 1996 to 2004
      • CAS50 packet format
      • CAS50 data types
      • CAS50 flows
    • CAS100 protocol – Serial protocol used by AFX / Graph 100
      • CAS100 packet format
      • CAS100 data types
      • CAS100 flows
    • CAS300 – Serial and USB protocol used by Classpad 300 / 330 (+)
      • CAS300 packet format
      • CAS300 commands
      • CAS300 flows
    • Protocol 7.00 – Serial and USB protocol used by post fx-9860G calculators
      • Specific formats for Protocol 7.00
      • Protocol 7.00 packet format
      • Protocol 7.00 communication flows
      • Known Protocol 7.00 commands by CASIO
      • Known Protocol 7.00 command extensions in fxRemote
      • Protocol 7.00 use cases
      • Known hardware identifiers for Protocol 7.00
    • Protocol 7.00 Screenstreaming – fx-9860G and fx-CG screenstreaming
      • Protocol 7.00 Screenstreaming packet format
      • Protocol 7.00 Screenstreaming communication flows
    • USB Mass Storage (UMS)
  • Cahute features
    • System compatibility
    • Contexts
    • Links and mediums
    • Files
    • Main memory data
    • Logging facilities
  • Cahute internals
    • Internal compatibility utilities
    • Links and medium internals
    • File internals
    • Characters, encodings and conversions
  • Command line reference
    • CaS command-line reference
    • p7 command line reference
    • p7os command line reference
    • p7screen command line reference
    • xfer9860 command line reference
  • Header reference
    • <cahute.h> – Main header for Cahute
      • <cahute/cdefs.h> – Basic definitions for Cahute
      • <cahute/config.h> – Cahute configuration details
      • <cahute/context.h> – Context management for Cahute
      • <cahute/data.h> – Calculator data resource and methods for Cahute
      • <cahute/detection.h> – Device detection for Cahute
      • <cahute/error.h> – Error definitions for Cahute
      • <cahute/file.h> – File related utilities for Cahute
      • <cahute/link.h> – Calculator link resource and methods for Cahute
      • <cahute/logging.h> – Logging control for Cahute
      • <cahute/path.h> – Path related utilities for Cahute
      • <cahute/picture.h> – Picture format related utilities for Cahute
      • <cahute/text.h> – Text encoding related utilities for Cahute
  • CMake setting reference
  • Project management
    • Project governance
    • Git and release versioning
    • Community feedback
    • Contribution style
    • Coding style
Back to top

<cahute/link.h> – Calculator link resource and methods for Cahute¶

This header declares link-related utilities for Cahute.

Type definitions¶

struct cahute_device_info¶

Device information.

unsigned long cahute_device_info_flags¶

Flags for the link information.

CAHUTE_DEVICE_INFO_FLAG_PREPROG¶

Preprogrammed ROM information available.

CAHUTE_DEVICE_INFO_FLAG_BOOTCODE¶

Bootcode information available.

CAHUTE_DEVICE_INFO_FLAG_OS¶

OS information available.

unsigned long cahute_device_info_rom_capacity¶

Preprogrammed ROM capacity, in KiB.

Only available if the CAHUTE_DEVICE_INFO_FLAG_PREPROG flag is set.

char const *cahute_device_info_rom_version¶

Preprogrammed ROM version.

Only available if the CAHUTE_DEVICE_INFO_FLAG_PREPROG flag is set.

unsigned long cahute_device_info_flash_rom_capacity¶

Flash ROM capacity, in KiB.

unsigned long cahute_device_info_ram_capacity¶

RAM capacity, in KiB.

char const *cahute_device_info_bootcode_version¶

Bootcode version.

Only available if the CAHUTE_DEVICE_INFO_FLAG_BOOTCODE flag is set.

unsigned long cahute_device_info_bootcode_offset¶

Bootcode offset.

Only available if the CAHUTE_DEVICE_INFO_FLAG_BOOTCODE flag is set.

unsigned long cahute_device_info_bootcode_size¶

Bootcode size, in KiB.

Only available if the CAHUTE_DEVICE_INFO_FLAG_BOOTCODE flag is set.

char const *cahute_device_info_os_version¶

OS version.

Only available if the CAHUTE_DEVICE_INFO_FLAG_OS flag is set.

unsigned long cahute_device_info_os_offset¶

OS offset.

Only available if the CAHUTE_DEVICE_INFO_FLAG_OS flag is set.

unsigned long cahute_device_info_os_size¶

OS size, in KiB.

Only available if the CAHUTE_DEVICE_INFO_FLAG_OS flag is set.

char const *cahute_device_info_product_id¶

Null-terminated product identifier, up to 16 characters.

char const *cahute_device_info_username¶

Null-terminated username, up to 20 characters long.

char const *cahute_device_info_organisation¶

Null-terminated organisation, up to 20 characters long.

char const *cahute_device_info_hwid¶

Null-terminated hardware identifier, up to 8 characters.

char const *cahute_device_info_cpuid¶

Null-terminated hardware platform identifier, up to 16 characters.

struct cahute_storage_entry¶

Entry when listing the contents of a storage device or directory.

char const *cahute_storage_entry_directory¶

If the entry is a directory, the name of the directory.

If the entry is a file, the optional name of the directory in which the file is present; this can be set to NULL if the file is present at root.

char const *cahute_storage_entry_name¶

If the entry is a directory, this is set to NULL.

If the entry is a file, the file name.

unsigned long cahute_storage_entry_size¶

Size in bytes of the file.

struct cahute_link¶

Link to a calculator, that can be used to run operations on the calculator, or receive data such as screenstreaming data.

This type is opaque, and such resources must be created using cahute_open_usb_link(), cahute_open_simple_usb_link() or cahute_open_serial_link().

typedef int (cahute_confirm_overwrite_func)(void *cookie)¶

Function that can be called to confirm overwrite.

See cahute_send_file_to_storage() for more information.

typedef int (cahute_list_storage_entry_func)(void *cookie, cahute_storage_list_entry const *entry)¶

Function that can be called for every storage device entry.

See cahute_list_storage_entries() for more information.

typedef int (cahute_progress_func)(void *cookie, unsigned long step, unsigned long total)¶

Function that can be called to display progress, when step step out of total has just finished.

See cahute_send_file_to_storage() and cahute_request_file_from_storage() for more information.

Link management related function declarations¶

int cahute_open_serial_link(cahute_context *context, cahute_link **linkp, unsigned long flags, char const *name, unsigned long speed)¶

Open a link over a serial modem.

Warning

In case of error, the value of *linkp mustn’t be used nor freed.

The format of the device name or path will vary depending on the platform:

  • On Microsoft Windows, it will either be the DOS COM device name (e.g. COM3) or the path to the device.

  • On other POSIX-compatible platforms, it will be the path to the device, usually /dev/cu* or /dev/tty* (e.g. /dev/ttyUSB0 for a serial link over a USB-serial cable);

  • On AmigaOS, it will be the serial unit number with the case-insensitive U= or UNIT= keyword parameter, e.g. unit=0 for the built-in serial device.

Available device names can be probed using cahute_detect_serial(), although the list may be incomplete and other devices may be used.

Since serial links do not offer any metadata, the protocol to use on the serial link is selected manually, amongst the following:

CAHUTE_SERIAL_PROTOCOL_DEFAULT¶

Depending on the other set flags:

  • Use CAHUTE_SERIAL_PROTOCOL_AUTO if CAHUTE_SERIAL_RECEIVER is set;

  • Otherwise, use CAHUTE_SERIAL_PROTOCOL_AUTO_CAS50.

This is the default value for the protocol.

CAHUTE_SERIAL_PROTOCOL_NONE¶

Do not use a protocol.

This renders all of the functions from Link medium access related function declarations accessible on the created link.

CAHUTE_SERIAL_PROTOCOL_CAS40¶

Use CAS40 protocol – Serial protocol used by pre-1996 calculators.

CAHUTE_SERIAL_PROTOCOL_CAS50¶

Use CAS50 protocol – Serial protocol used by calculators from 1996 to 2004.

CAHUTE_SERIAL_PROTOCOL_CAS100¶

Use CAS100 protocol – Serial protocol used by AFX / Graph 100.

CAHUTE_SERIAL_PROTOCOL_CAS300¶

Use CAS300 – Serial and USB protocol used by Classpad 300 / 330 (+).

CAHUTE_SERIAL_PROTOCOL_SEVEN¶

Use Protocol 7.00 – Serial and USB protocol used by post fx-9860G calculators.

CAHUTE_SERIAL_PROTOCOL_SEVEN_OHP¶

Use Protocol 7.00 Screenstreaming – fx-9860G and fx-CG screenstreaming.

CAHUTE_SERIAL_PROTOCOL_AUTO¶

Use automatic protocol detection on reception.

Note

This is the default value if CAHUTE_SERIAL_RECEIVER is set. See CAHUTE_SERIAL_PROTOCOL_DEFAULT for more information.

Warning

This can only be used if:

  • CAHUTE_SERIAL_RECEIVER is set;

  • CAHUTE_SERIAL_NOCHECK is not set, since we are tweaking the checking flow to determine the protocol on the other side.

CAHUTE_SERIAL_PROTOCOL_AUTO_CAS40¶

Use automatic protocol detection, and assume CAS40 if CASIOLINK.

CAHUTE_SERIAL_PROTOCOL_AUTO_CAS50¶

Use automatic protocol detection, and assume CAS50 if CASIOLINK.

Note

This is the default value if CAHUTE_SERIAL_RECEIVER is not set. See CAHUTE_SERIAL_PROTOCOL_DEFAULT for more information.

CAHUTE_SERIAL_PROTOCOL_AUTO_CAS100¶

Use automatic protocol detection, and assume CAS100 if CASIOLINK.

CAHUTE_SERIAL_PROTOCOL_AUTO_CAS300¶

Use automatic protocol detection, and assume CAS300 if CASIOLINK.

Since the number of stop bits may be selectable on the calculator, it can also be selected manually, amongst the following:

CAHUTE_SERIAL_STOP_ONE¶

Use 1 stop bit.

CAHUTE_SERIAL_STOP_TWO¶

Use 2 stop bits.

Since the parity may also be selectable on the calculator, it can also be selected manually, amongst the following:

CAHUTE_SERIAL_PARITY_OFF¶

Disable parity checks.

CAHUTE_SERIAL_PARITY_EVEN¶

Use even parity checks.

CAHUTE_SERIAL_PARITY_ODD¶

Use odd parity checks.

Note

fx-9860G calculators and derivatives, i.e. the ones you will be the most likely to encounter, use protocol 7.00 with 2 stop bits and no parity when establishing a new connection.

The LINK app on such calculators does not allow to change these settings, and the only way for the link to use different settings is if the connection has already been established and command 02 “Set link settings” was issued to change the serial link parameters for the current connection.

If the device uses XON/XOFF software control, it can also be selected manually, amongst the following:

CAHUTE_SERIAL_XONXOFF_DISABLE¶

Disable XON/XOFF software control.

CAHUTE_SERIAL_XONXOFF_ENABLE¶

Enable XON/XOFF software control.

Default serial settings depend on the protocol you select:

Protocol

Speed

Parity

Stop bits

XON/XOFF

NONE

9600

OFF

TWO

DISABLED

CAS40, AUTO_CAS40

4800

EVEN

TWO

DISABLED

CAS50, AUTO_CAS50

9600

OFF

TWO

DISABLED

CAS100, AUTO_CAS100

38400

OFF

TWO

DISABLED

CAS300, AUTO_CAS300

38400

OFF

TWO

ENABLED

SEVEN, SEVEN_OHP, AUTO

9600

OFF

TWO

DISABLED

Warning

These serial settings may only apply to the first part of the communication, since in some of the aforementioned protocols and CASIOLINK variants, both devices can negotiate different serial parameters and switch to them.

If the device uses DTR and the cable supports it, it can be set manually as well, amongst the following:

CAHUTE_SERIAL_DTR_IGNORE¶

Ignore the status of the DTR line (by default).

This is the most portable option, since the platform may not allow Cahute to set the DTR line.

CAHUTE_SERIAL_DTR_DISABLE¶

Disable the DTR line when the link is opened, and leave it disabled.

This may cause a CAHUTE_ERROR_IMPL error if the platform does not allow Cahute to set the DTR line.

CAHUTE_SERIAL_DTR_ENABLE¶

Enable the DTR line when the link is opened, and leave it enabled.

This may cause a CAHUTE_ERROR_IMPL error if the platform does not allow Cahute to set the DTR line.

If the device uses RTS and the cable supports it, it can also be set manually, amongst the following:

CAHUTE_SERIAL_RTS_IGNORE¶

Ignore the status of the RTS line (by default).

This is the most portable option, since the platform may not allow Cahute to set the RTS line.

CAHUTE_SERIAL_RTS_DISABLE¶

Disable the RTS line when the link is opened, and leave it disabled.

This may cause a CAHUTE_ERROR_IMPL error if the platform does not allow Cahute to set the RTS line.

CAHUTE_SERIAL_RTS_ENABLE¶

Enable the RTS line when the link opened, and leave it enabled.

This may cause a CAHUTE_ERROR_IMPL error if the platform does not allow Cahute to set the RTS line.

CAHUTE_SERIAL_RTS_HANDSHAKE¶

Use RTS/CTS handshaking.

This may cause a CAHUTE_ERROR_IMPL error if the platform does not support it, and does not allow the necessary pin interactions.

Protocol-specific behaviour can be tweaked using the following flags:

CAHUTE_SERIAL_RECEIVER¶

If this flag is provided, the link starts out as a passive / receiver side rather than an active / sender side.

CAHUTE_SERIAL_NOCHECK¶

If this flag is provided:

  • If CAHUTE_SERIAL_RECEIVER is provided, the initial handshake is no longer required from the sender or active side, albeit still accepted.

  • Otherwise, the initial handshake will not be done when the link is established on the underlying medium.

This flag is mostly useful when resuming a connection initiated by another process, or when the passive process does not require or implement the initial handshake.

Warning

This cannot be used if CAHUTE_SERIAL_PROTOCOL_AUTO is used, as we tweak the checking flow to determine the protocol of the other side.

CAHUTE_SERIAL_NODISC¶

If this flag is provided, and CAHUTE_SERIAL_RECEIVER is not provided, device discovery is not run once the link is established to get the device information.

This flag is mostly useful when dealing with bootcode or custom link implementations that may not have implemented this command. It is not recommended when communicating with the LINK application, since it prevents Cahute from being able to predict which commands will be available without crashing the link.

It is only effective when Protocol 7.00 – Serial and USB protocol used by post fx-9860G calculators or CAS300 – Serial and USB protocol used by Classpad 300 / 330 (+) is used.

CAHUTE_SERIAL_NOTERM¶

If this flag is provided, and CAHUTE_SERIAL_RECEIVER is not provided, the terminate flow is not run when the link is closed.

This flag is mostly useful to let the connection still opened for other processes to run commands. Combined with CAHUTE_SERIAL_NOCHECK, provided the protocol is set explicitely, it allows running multiple shell commands on the same connection.

Parameters:
  • context – Context in which to open the link.

  • linkp – The pointer to set the opened link to.

  • flags – The flags to set to the serial link.

  • name – The name or path of the serial link to open.

  • speed – The speed (in bauds) to open the serial link with, or 0 to select the default serial speed for the protocol and CASIOLINK variant.

Returns:

The error, or 0 if the operation was successful.

int cahute_open_usb_link(cahute_context *context, cahute_link **linkp, unsigned long flags, int bus, int address)¶

Open a link with a USB device.

Warning

In case of error, the value of *linkp mustn’t be used nor freed.

The protocol to use is partially determined using the USB device metadata. See USB detection for CASIO calculators for more information.

Protocol-specific behaviour can be tweaked using the following flags:

CAHUTE_USB_NOCHECK¶

If this flag is provided:

  • If CAHUTE_USB_RECEIVER is provided, the initial handshake is no longer required from the sender or active side, albeit still accepted.

  • Otherwise, the initial handshake will not be done when the link is established on the underlying medium.

This flag is mostly useful when resuming a connection initiated by another process, or when the passive process does not require or implement the initial handshake.

If this flag is provided, either CAHUTE_USB_SEVEN, CAHUTE_USB_CAS300 or CAHUTE_USB_OHP must be provided.

It is only effective when using Protocol 7.00. See Protocol 7.00 – Serial and USB protocol used by post fx-9860G calculators for more information.

CAHUTE_USB_NODISC¶

If this flag is provided, and CAHUTE_SERIAL_RECEIVER is not provided, device discovery is not run once the link is established to get the device information.

This flag is mostly useful when dealing with bootcode or custom link implementations that may not have implemented this command. It is not recommended when communicating with the LINK application, since it prevents Cahute from being able to predict which commands will be available without crashing the link.

It is only effective when Protocol 7.00 – Serial and USB protocol used by post fx-9860G calculators or CAS300 – Serial and USB protocol used by Classpad 300 / 330 (+) is used.

CAHUTE_USB_NOTERM¶

If this flag is provided, and CAHUTE_USB_RECEIVER is not provided, the terminate flow is not run when the link is closed.

This flag is mostly useful to let the connection still opened for other processes to run commands. Combined with CAHUTE_USB_NOCHECK, it allows running multiple shell commands on the same connection.

It is only effective when using protocol 7.00. See Protocol 7.00 – Serial and USB protocol used by post fx-9860G calculators for more information.

CAHUTE_USB_RECEIVER¶

If this flag is provided, we will act as a receiver / passive side rather than a sender.

This is mostly useful if the “Transmit” option is selected on the calculator’s LINK application, instead of the “Receive” option.

CAHUTE_USB_SEVEN¶

In case of serial USB devices, force using Protocol 7.00 or Protocol 7.00 Screenstreaming instead of automatic protocol detection.

This flag is incompatible with CAHUTE_USB_CAS300.

CAHUTE_USB_CAS300¶

In case of serial USB devices, force using CASIOLINK with variant CAS300 instead of automatic protocol detection.

This flag is incompatible with CAHUTE_USB_SEVEN and CAHUTE_USB_OHP.

CAHUTE_USB_OHP¶

If this flag is provided, the calculator is assumed to use the link for screenstreaming purposes.

For example, with the fx-9860G and compatible, this prompts the link to use Protocol 7.00 Screenstreaming instead of Protocol 7.00.

This flag is incompatible with CAHUTE_USB_CAS300.

See Protocol 7.00 Screenstreaming – fx-9860G and fx-CG screenstreaming for more information.

CAHUTE_USB_NOPROTO¶

Do not use a protocol.

This renders all of the functions from Link medium access related function declarations accessible on the created link.

Parameters:
  • context – Context in which to open the link.

  • linkp – The pointer to set the opened link to.

  • flags – The flags to set to the USB link.

  • bus – The bus number of the USB calculator to open a link with.

  • address – The device number of the calculator to open a link with.

Returns:

The error, or 0 if the operation was successful.

int cahute_open_simple_usb_link(cahute_context *context, cahute_link **linkp, unsigned long flags)¶

Open a link to a single USB device.

Warning

In case of error, the value of *linkp mustn’t be used nor freed.

This function expects exactly one compatible device to be connected by USB, leading to the following cases:

  • If there are more than one, CAHUTE_ERROR_TOO_MANY will be returned.

  • If there are none, the function will retry a few times before giving up and returning CAHUTE_ERROR_NOT_FOUND.

Note

Usage of this function is only useful for simple scripts that assume only up to one calculator is connected at a time to the system. If you plan on multiple being connected simultaneously, see cahute_detect_usb() and cahute_open_usb_link().

Flags from cahute_open_usb_link() can be used. In addition, it is possible to filter in the USB devices to look for, by providing one of the following constants in the flags:

CAHUTE_USB_FILTER_ANY¶

Open any USB device (by default).

CAHUTE_USB_FILTER_SERIAL¶

Open devices identifying themselves as speaking an application protocol over USB bulk transfers.

See Serial transport over USB bulk for more information.

CAHUTE_USB_FILTER_UMS¶

Open devices identifying themselves as speaking an application protocol over USB Mass Storage / SCSI.

See USB Mass Storage (UMS) transport for more information.

Warning

If the filter is provided and CAHUTE_USB_FILTER_SERIAL is included and CAHUTE_USB_NOCHECK is defined, either CAHUTE_USB_SEVEN or CAHUTE_USB_CAS300 must be provided to determine what protocol to adopt if a serial USB calculator was picked.

Parameters:
  • context – Context in which to run the function.

  • linkp – The pointer to set to the opened link.

  • flags – The flags to set the USB link.

Returns:

The error, or 0 if the operation was successful.

void cahute_close_link(cahute_link *link)¶

Close and free a link.

Parameters:
  • link – The link to close.

Link medium access related function declarations¶

Warning

These functions can only be used when no protocol is used with a link, i.e. when:

  • CAHUTE_SERIAL_PROTOCOL_NONE is used with cahute_open_serial_link();

  • CAHUTE_USB_NOPROTO is used with cahute_open_usb_link() or cahute_open_simple_usb_link.

int cahute_receive_on_link(cahute_link *link, cahute_u8 *buf, size_t size, unsigned long first_timeout, unsigned long next_timeout)¶

Read exactly size bytes of data into the buffer.

Warning

This function does not provide the number of bytes that have been read in case of error (with the exception of CAHUTE_ERROR_TIMEOUT_START, which implies that no bytes have been read).

Errors to be expected from this function are the following:

CAHUTE_ERROR_TIMEOUT_START

The first byte was not received in a timely manner. This can only occur if first_timeout was not set to 0.

CAHUTE_ERROR_TIMEOUT

A byte past the first one was not received in a timely manner. This can only occur if next_timeout was not set to 0.

CAHUTE_ERROR_GONE

The device is no longer present, usually either because the USB cable has been unplugged on one end or the other, or the serial adapter has been unplugged from the host.

CAHUTE_ERROR_UNKNOWN

The medium-specific operations have yielded an error code that Cahute did not interpret. Some details can usually be found in the logs.

Parameters:
  • link – Generic link to receive data on.

  • buf – Buffer in which to write the received data.

  • size – Size of the data to write to the buffer.

  • first_timeout – Maximum delay to wait before the first byte of the data, in milliseconds. If this is set to 0, the first byte will be awaited indefinitely.

  • next_timeout – Maximum delay to wait between two bytes of the data, or before the last byte, in milliseconds. If this is set to 0, next bytes will be awaited indefinitely.

Returns:

Error, or CAHUTE_OK.

int cahute_send_on_link(cahute_link *link, cahute_u8 const *buf, size_t size)¶

Write exactly size bytes of data to the link.

Errors to be expected from this function are the following:

CAHUTE_ERROR_GONE

The device is no longer present, usually either because the USB cable has been unplugged on one end or the other, or the serial adapter has been unplugged from the host.

CAHUTE_ERROR_UNKNOWN

The medium-specific operations have yielded an error code that Cahute did not interpret. Some details can usually be found in the logs.

Parameters:
  • link – Generic link to send data on.

  • buf – Buffer from which to read the data to send.

  • size – Size of the data to read and send.

Returns:

Error, or CAHUTE_OK.

int cahute_set_serial_params_to_link(cahute_link *link, unsigned long flags, unsigned long speed)¶

Set the serial parameters to the link medium.

Accepted flags are a subset of the flags for cahute_open_serial():

  • CAHUTE_SERIAL_STOP_* (stop bits);

  • CAHUTE_SERIAL_PARITY_* (parity);

  • CAHUTE_SERIAL_XONXOFF_* (XON/XOFF software control);

  • CAHUTE_SERIAL_DTR_* (DTR hardware control);

  • CAHUTE_SERIAL_RTS_* (RTS hardware control).

Parameters:
  • link – Generic link to set the serial parameters to.

  • flags – Flags to set to the link medium.

  • speed – Speed to set to the link medium.

Returns:

Error, or CAHUTE_OK.

Device metadata access related function declarations¶

int cahute_get_device_info(cahute_link *link, cahute_device_info **infop)¶

Gather information on the device (calculator or other).

Warning

In all cases, *infop musn’t be freed. In case of error, *infop mustn’t be used.

Parameters:
  • link – The link on which to gather information.

  • infop – The pointer to set to the information to.

Returns:

The error, or 0 if the operation was successful.

Data transfer related function declarations¶

int cahute_receive_data(cahute_link *link, cahute_data **datap, unsigned long timeout)¶

Receive the next data from the device.

Warning

If the function returns an error, **datap must not be used.

If the function returns CAHUTE_OK (0), the caller is assumed to take ownership of *datap, which means it is also ultimately responsible for destroying it once the resource is no longer needed using cahute_destroy_data().

Parameters:
  • link – Link to the device.

  • datap – Pointer to the data to set to the newly allocated one.

  • timeout – Timeout in milliseconds in which to receive the data. If this is set to 0, the timeout is considered infinite.

Returns:

Error, or 0 if the operation was successful.

int cahute_receive_screen(cahute_link *link, cahute_frame const **framep, unsigned long timeout)¶

Receive the next screen.

Warning

The frame must not be deallocated.

Parameters:
  • link – Link with which to receive the screen frame.

  • framep – Pointer to the frame to define.

  • timeout – Timeout in milliseconds in which to receive the screen. If this is set to 0, the timeout is considered infinite.

Returns:

Error, or 0 if the operation was successful.

Link control related function declarations¶

int cahute_negotiate_serial_params(cahute_link *link, unsigned long flags, unsigned long speed)¶

Negotiate new parameters for a serial link, and update the medium parameters to these.

The accepted flags here are among CAHUTE_SERIAL_STOP_* and CAHUTE_SERIAL_PARITY_*.

Parameters:
  • link – Link to which to define the new attributes.

  • flags – New flags to set to the serial link.

  • speed – New speed to set to the serial link.

Returns:

Error, or 0 if the operation was successful.

int cahute_request_storage_capacity(cahute_link *link, char const *storage, unsigned long *capacityp)¶

Request the currently available capacity on the provided storage device.

If this function returns an error, the contents of *capacityp is left intact, and may be undefined.

Parameters:
  • link – Link to the device.

  • storage – Name of the storage device for which to get the currently available capacity.

  • capacityp – Pointer to the capacity to fill.

Returns:

Error, or 0 if the operation was successful.

int cahute_send_file_to_storage(cahute_link *link, unsigned long flags, char const *directory, char const *name, char const *storage, cahute_file *file, cahute_confirm_overwrite_func *overwrite_func, void *overwrite_cookie, cahute_progress_func *progress_func, void *progress_cookie)¶

Send a file to a storage device on the calculator.

Note

The provided filep parameter will be used for reading and seeking, in order to estimate the file size.

If an overwrite confirmation function is provided and the calculator requests confirmation for overwriting, said function is called. Then:

  • If the function returns 0, the overwrite is rejected, therefore the file is not sent.

  • If the function returns any other value, the overwrite is confirmed, and the function transfers the file over.

Flags that can be set to this function are the following:

CAHUTE_SEND_FILE_FLAG_FORCE¶

If this flag is set, overwrite is forced without using the callback functions.

CAHUTE_SEND_FILE_FLAG_OPTIMIZE¶

If this flag is set, the available capacity in the targeted storage is requested. If it is not considered enough to store the file, an optimize command will be issued beforehand.

CAHUTE_SEND_FILE_FLAG_DELETE¶

If this flag is set and a file is already present in the destination file name in the selected directory, the file is deleted before any other command.

Combined with CAHUTE_SEND_FILE_FLAG_OPTIMIZE, this ensures that the space occupied by an existing file is claimed back before the new file is sent.

See Send a file to storage for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • flags – Flags for the function.

  • directory – Name of the directory in which to place the file, or NULL if the file should be placed at root.

  • name – Name of the file in the target storage device.

  • storage – Name of the storage device on which to place the file.

  • file – File to read data and estimate file size from.

  • overwrite_func – Pointer to the overwrite function to call. If this is set to NULL, the overwrite will be systematically rejected if requested by the calculator.

  • overwrite_cookie – Cookie to pass to the overwrite confirmation function.

  • progress_func – Pointer to the optional progress function to call once for every step in the transfer process.

  • progress_cookie – Cookie to pass to the progress function.

Returns:

Error, or 0 if the operation was successful.

int cahute_request_file_from_storage(cahute_link *link, char const *directory, char const *name, char const *storage, void const *path, int path_type, cahute_progress_func *progress_func, void *progress_cookie)¶

Request a file from a storage device on the calculator.

See Request a file from storage for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • directory – Name of the directory from which to request the file, or NULL if the file should be placed at root.

  • name – Name of the file to request.

  • storage – Name of the storage device from which to request the file.

  • path – Path to the file to create and write the received content into. If NULL, the requested file will be written in standard output.

  • path_type – Type of the path.

  • progress_func – Pointer to the optional progress function to call once for every step in the transfer process.

  • progress_cookie – Cookie to pass to the progress function.

Returns:

Error, or 0 if the operation was successful.

int cahute_copy_file_on_storage(cahute_link *link, char const *source_directory, char const *source_name, char const *target_directory, char const *target_name, char const *storage)¶

Copy a file on a storage device on the calculator.

See Copy a file to another on storage for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • source_directory – Name of the directory in which to retrieve the source file.

  • source_name – Name of the source file to copy.

  • target_directory – Name of the directory in which to create the copy.

  • target_name – Name of the copy.

  • storage – Name of the storage device on which to copy.

Returns:

Error, or 0 if the operation was successful.

int cahute_delete_file_from_storage(cahute_link *link, char const *directory, char const *name, char const *storage)¶

Delete a file from a storage device on the calculator.

See Delete a file from storage for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • directory – Name of the directory from which to delete the file, or NULL if the file should be placed at root.

  • name – Name of the file to delete.

  • storage – Name of the storage device from which to delete the file.

Returns:

Error, or 0 if the operation was successful.

int cahute_list_storage_entries(cahute_link *link, char const *storage, cahute_list_storage_entry_func *callback, void *cookie)¶

List files and directories on a storage device on the calculator.

For every entry, the callback function is called. If it returns a value other than 0, the file listing is interrupted.

See List files on storage for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • storage – Storage on which to list files and directories.

  • func – Function to call back with every found entry.

  • cookie – Cookie to pass to the function.

Returns:

Error, or 0 if the operation was unsuccessful.

int cahute_reset_storage(cahute_link *link, char const *storage)¶

Request a reset of the provided storage device by the calculator.

See Reset a storage device for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • storage – Name of the storage device.

Returns:

Error, or 0 if the operation was successful.

int cahute_optimize_storage(cahute_link *link, char const *storage)¶

Request optimization for the provided storage device by the calculator.

See Optimize a storage device for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • storage – Name of the storage device.

Returns:

Error, or 0 if the operation was successful.

int cahute_backup_rom(cahute_link *link, cahute_u8 **romp, size_t *sizep)¶

Request the flash ROM contents from the calculator.

*romp is allocated dynamically, and must be free’d once no longer used. In case of error, *romp must not be read, used or free’d.

See Back up the system for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • romp – Pointer to the flash ROM contents to allocate.

  • sizep – Pointer to the size to define.

Returns:

Error, or 0 if the operation was successful.

int cahute_upload_and_run_program(cahute_link *link, cahute_u8 const *program, size_t program_size, unsigned long load_address, unsigned long start_address, cahute_progress_func *progress_func, void *progress_cookie)¶

Upload and run a program on the calculator.

See Upload and run an executable program for the use case with Protocol 7.00.

Parameters:
  • link – Link to the device.

  • program – Pointer to the program to upload and run.

  • program_size – Size of the program to upload and run.

  • load_address – Remote address at which to load the program.

  • start_address – Remote address at which to start the program.

  • progress_func – Pointer to the optional progress function to call once for every step in the transfer process.

  • progress_cookie – Cookie to pass to the progress function.

Returns:

Error, or 0 if the operation was successful.

int cahute_flash_system_using_fxremote_method(cahute_link *link, cahute_u8 const *system, size_t system_size)¶

Flash a new system on the calculator, assuming the passive side is running fxRemote’s Update.EXE program.

The following flags are available:

CAHUTE_FLASH_FLAG_RESET_SMEM¶

Whether to also reset the storage memory on flash, or not.

Parameters:
  • link – Link to the device.

  • system – System to flash onto the calculator.

  • system_size – Size of the system to flash.

Returns:

Error, or 0 if the operation was successful.

Next
<cahute/logging.h> – Logging control for Cahute
Previous
<cahute/file.h> – File related utilities for Cahute
Copyright © 2024, Thomas Touhey
Made with Sphinx and @pradyunsg's Furo
On this page
  • <cahute/link.h> – Calculator link resource and methods for Cahute
    • Type definitions
    • Link management related function declarations
    • Link medium access related function declarations
    • Device metadata access related function declarations
    • Data transfer related function declarations
    • Link control related function declarations