/ 
Tinkerforge-2.1.30
River stage zero No dependents
/ Tinkerforge::BrickRED

NAME

Tinkerforge::BrickRED - Executes user programs and controls other Bricks/Bricklets standalone

CONSTANTS

DEVICE_IDENTIFIER

This constant is used to identify a RED Brick.

The get_identity() subroutine and the CALLBACK_ENUMERATE callback of the IP Connection have a device_identifier parameter to specify the Brick's or Bricklet's type.

DEVICE_DISPLAY_NAME

This constant represents the display name of a RED Brick.

CALLBACK_ASYNC_FILE_READ

This constant is used with the register_callback() subroutine to specify the CALLBACK_ASYNC_FILE_READ callback.

CALLBACK_ASYNC_FILE_WRITE

This constant is used with the register_callback() subroutine to specify the CALLBACK_ASYNC_FILE_WRITE callback.

CALLBACK_FILE_EVENTS_OCCURRED

This constant is used with the register_callback() subroutine to specify the CALLBACK_FILE_EVENTS_OCCURRED callback.

CALLBACK_PROCESS_STATE_CHANGED

This constant is used with the register_callback() subroutine to specify the CALLBACK_PROCESS_STATE_CHANGED callback.

CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED

This constant is used with the register_callback() subroutine to specify the CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED callback.

CALLBACK_PROGRAM_PROCESS_SPAWNED

This constant is used with the register_callback() subroutine to specify the CALLBACK_PROGRAM_PROCESS_SPAWNED callback.

FUNCTION_CREATE_SESSION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_EXPIRE_SESSION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_EXPIRE_SESSION_UNCHECKED

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_KEEP_SESSION_ALIVE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_RELEASE_OBJECT

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_RELEASE_OBJECT_UNCHECKED

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_ALLOCATE_STRING

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_TRUNCATE_STRING

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_STRING_LENGTH

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_STRING_CHUNK

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_STRING_CHUNK

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_ALLOCATE_LIST

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_LIST_LENGTH

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_LIST_ITEM

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_APPEND_TO_LIST

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_REMOVE_FROM_LIST

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_OPEN_FILE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_CREATE_PIPE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_FILE_INFO

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_READ_FILE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_READ_FILE_ASYNC

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_ABORT_ASYNC_FILE_READ

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_WRITE_FILE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_WRITE_FILE_UNCHECKED

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_WRITE_FILE_ASYNC

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_FILE_POSITION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_FILE_POSITION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_FILE_EVENTS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_FILE_EVENTS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_OPEN_DIRECTORY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_DIRECTORY_NAME

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_NEXT_DIRECTORY_ENTRY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_REWIND_DIRECTORY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_CREATE_DIRECTORY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROCESSES

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SPAWN_PROCESS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_KILL_PROCESS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROCESS_COMMAND

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROCESS_IDENTITY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROCESS_STDIO

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROCESS_STATE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAMS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_DEFINE_PROGRAM

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_PURGE_PROGRAM

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAM_IDENTIFIER

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAM_ROOT_DIRECTORY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_PROGRAM_COMMAND

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAM_COMMAND

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_PROGRAM_STDIO_REDIRECTION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAM_STDIO_REDIRECTION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_PROGRAM_SCHEDULE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAM_SCHEDULE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_PROGRAM_SCHEDULER_STATE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_CONTINUE_PROGRAM_SCHEDULE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_START_PROGRAM

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_LAST_SPAWNED_PROGRAM_PROCESS

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_CUSTOM_PROGRAM_OPTION_NAMES

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_SET_CUSTOM_PROGRAM_OPTION_VALUE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_CUSTOM_PROGRAM_OPTION_VALUE

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_REMOVE_CUSTOM_PROGRAM_OPTION

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTION_GET_IDENTITY

This constant is used with the get_response_expected(), set_response_expected() and set_response_expected_all() subroutines.

FUNCTIONS

new()

Creates an object with the unique device ID *uid* and adds it to the IP Connection *ipcon*.

create_session()
expire_session()
expire_session_unchecked()
keep_session_alive()
release_object()

Decreases the reference count of an object by one and returns the resulting error code. If the reference count reaches zero the object gets destroyed.

release_object_unchecked()
allocate_string()

Allocates a new string object, reserves ``length_to_reserve`` bytes memory for it and sets up to the first 60 bytes. Set ``length_to_reserve`` to the length of the string that should be stored in the string object.

Returns the object ID of the new string object and the resulting error code.

truncate_string()

Truncates a string object to ``length`` bytes and returns the resulting error code.

get_string_length()

Returns the length of a string object and the resulting error code.

set_string_chunk()

Sets a chunk of up to 58 bytes in a string object beginning at ``offset``.

Returns the resulting error code.

get_string_chunk()

Returns a chunk up to 63 bytes from a string object beginning at ``offset`` and returns the resulting error code.

allocate_list()

Allocates a new list object and reserves memory for ``length_to_reserve`` items. Set ``length_to_reserve`` to the number of items that should be stored in the list object.

Returns the object ID of the new list object and the resulting error code.

When a list object gets destroyed then the reference count of each object in the list object is decreased by one.

get_list_length()

Returns the length of a list object in items and the resulting error code.

get_list_item()

Returns the object ID and type of the object stored at ``index`` in a list object and returns the resulting error code.

Possible object types are:

* String = 0 * List = 1 * File = 2 * Directory = 3 * Process = 4 * Program = 5

append_to_list()

Appends an object to a list object and increases the reference count of the appended object by one.

Returns the resulting error code.

remove_from_list()

Removes the object stored at ``index`` from a list object and decreases the reference count of the removed object by one.

Returns the resulting error code.

open_file()

Opens an existing file or creates a new file and allocates a new file object for it.

FIXME: name has to be absolute

The reference count of the name string object is increased by one. When the file object gets destroyed then the reference count of the name string object is decreased by one. Also the name string object is locked and cannot be modified while the file object holds a reference to it.

The ``flags`` parameter takes a ORed combination of the following possible file flags (in hexadecimal notation):

* ReadOnly = 0x0001 (O_RDONLY) * WriteOnly = 0x0002 (O_WRONLY) * ReadWrite = 0x0004 (O_RDWR) * Append = 0x0008 (O_APPEND) * Create = 0x0010 (O_CREAT) * Exclusive = 0x0020 (O_EXCL) * NonBlocking = 0x0040 (O_NONBLOCK) * Truncate = 0x0080 (O_TRUNC) * Temporary = 0x0100 * Replace = 0x0200

FIXME: explain *Temporary* and *Replace* flag

The ``permissions`` parameter takes a ORed combination of the following possible file permissions (in octal notation) that match the common UNIX permission bits:

* UserRead = 00400 * UserWrite = 00200 * UserExecute = 00100 * GroupRead = 00040 * GroupWrite = 00020 * GroupExecute = 00010 * OthersRead = 00004 * OthersWrite = 00002 * OthersExecute = 00001

Returns the object ID of the new file object and the resulting error code.

create_pipe()

Creates a new pipe and allocates a new file object for it.

The ``flags`` parameter takes a ORed combination of the following possible pipe flags (in hexadecimal notation):

* NonBlockingRead = 0x0001 * NonBlockingWrite = 0x0002

The length of the pipe buffer can be specified with the ``length`` parameter in bytes. If length is set to zero, then the default pipe buffer length is used.

Returns the object ID of the new file object and the resulting error code.

get_file_info()

Returns various information about a file and the resulting error code.

Possible file types are:

* Unknown = 0 * Regular = 1 * Directory = 2 * Character = 3 * Block = 4 * FIFO = 5 * Symlink = 6 * Socket = 7 * Pipe = 8

If the file type is *Pipe* then the returned name string object is invalid, because a pipe has no name. Otherwise the returned name string object was used to open or create the file object, as passed to :func:`Open File`.

The returned flags were used to open or create the file object, as passed to :func:`Open File` or :func:`Create Pipe`. See the respective function for a list of possible file and pipe flags.

FIXME: everything except flags and length is invalid if file type is *Pipe*

read_file()

Reads up to 62 bytes from a file object.

Returns the bytes read, the actual number of bytes read and the resulting error code.

If there is not data to be read, either because the file position reached end-of-file or because there is not data in the pipe, then zero bytes are returned.

If the file object was created by :func:`Open File` without the *NonBlocking* flag or by :func:`Create Pipe` without the *NonBlockingRead* flag then the error code *NotSupported* is returned.

read_file_async()

Reads up to 2\ :sup:`63`\ - 1 bytes from a file object asynchronously.

Reports the bytes read (in 60 byte chunks), the actual number of bytes read and the resulting error code via the :cb:`Async File Read` callback.

If there is not data to be read, either because the file position reached end-of-file or because there is not data in the pipe, then zero bytes are reported.

If the file object was created by :func:`Open File` without the *NonBlocking* flag or by :func:`Create Pipe` without the *NonBlockingRead* flag then the error code *NotSupported* is reported via the :cb:`Async File Read` callback.

abort_async_file_read()

Aborts a :func:`Read File Async` operation in progress.

Returns the resulting error code.

On success the :cb:`Async File Read` callback will report *OperationAborted*.

write_file()

Writes up to 61 bytes to a file object.

Returns the actual number of bytes written and the resulting error code.

If the file object was created by :func:`Open File` without the *NonBlocking* flag or by :func:`Create Pipe` without the *NonBlockingWrite* flag then the error code *NotSupported* is returned.

write_file_unchecked()

Writes up to 61 bytes to a file object.

Does neither report the actual number of bytes written nor the resulting error code.

If the file object was created by :func:`Open File` without the *NonBlocking* flag or by :func:`Create Pipe` without the *NonBlockingWrite* flag then the write operation will fail silently.

write_file_async()

Writes up to 61 bytes to a file object.

Reports the actual number of bytes written and the resulting error code via the :cb:`Async File Write` callback.

If the file object was created by :func:`Open File` without the *NonBlocking* flag or by :func:`Create Pipe` without the *NonBlockingWrite* flag then the error code *NotSupported* is reported via the :cb:`Async File Write` callback.

set_file_position()

Set the current seek position of a file object relative to ``origin``.

Possible file origins are:

* Beginning = 0 * Current = 1 * End = 2

Returns the resulting absolute seek position and error code.

If the file object was created by :func:`Create Pipe` then it has no seek position and the error code *InvalidSeek* is returned.

get_file_position()

Returns the current seek position of a file object and returns the resulting error code.

If the file object was created by :func:`Create Pipe` then it has no seek position and the error code *InvalidSeek* is returned.

set_file_events()
get_file_events()
open_directory()

Opens an existing directory and allocates a new directory object for it.

FIXME: name has to be absolute

The reference count of the name string object is increased by one. When the directory object is destroyed then the reference count of the name string object is decreased by one. Also the name string object is locked and cannot be modified while the directory object holds a reference to it.

Returns the object ID of the new directory object and the resulting error code.

get_directory_name()

Returns the name of a directory object, as passed to :func:`Open Directory`, and the resulting error code.

get_next_directory_entry()

Returns the next entry in a directory object and the resulting error code.

If there is not next entry then error code *NoMoreData* is returned. To rewind a directory object call :func:`Rewind Directory`.

Possible directory entry types are:

* Unknown = 0 * Regular = 1 * Directory = 2 * Character = 3 * Block = 4 * FIFO = 5 * Symlink = 6 * Socket = 7

rewind_directory()

Rewinds a directory object and returns the resulting error code.

create_directory()

FIXME: name has to be absolute

get_processes()
spawn_process()
kill_process()

Sends a UNIX signal to a process object and returns the resulting error code.

Possible UNIX signals are:

* Interrupt = 2 * Quit = 3 * Abort = 6 * Kill = 9 * User1 = 10 * User2 = 12 * Terminate = 15 * Continue = 18 * Stop = 19

get_process_command()

Returns the executable, arguments, environment and working directory used to spawn a process object, as passed to :func:`Spawn Process`, and the resulting error code.

get_process_identity()

Returns the process ID and the user and group ID used to spawn a process object, as passed to :func:`Spawn Process`, and the resulting error code.

The process ID is only valid if the state is *Running* or *Stopped*, see :func:`Get Process State`.

get_process_stdio()

Returns the stdin, stdout and stderr files used to spawn a process object, as passed to :func:`Spawn Process`, and the resulting error code.

get_process_state()

Returns the current state, timestamp and exit code of a process object, and the resulting error code.

Possible process states are:

* Unknown = 0 * Running = 1 * Error = 2 * Exited = 3 * Killed = 4 * Stopped = 5

The timestamp represents the UNIX time since when the process is in its current state.

The exit code is only valid if the state is *Error*, *Exited*, *Killed* or *Stopped* and has different meanings depending on the state:

* Error: error code for error occurred while spawning the process (see below) * Exited: exit status of the process * Killed: UNIX signal number used to kill the process * Stopped: UNIX signal number used to stop the process

Possible exit/error codes in *Error* state are:

* InternalError = 125 * CannotExecute = 126 * DoesNotExist = 127

The *CannotExecute* error can be caused by the executable being opened for writing.

get_programs()
define_program()
purge_program()
get_program_identifier()
get_program_root_directory()

FIXME: root directory is absolute: <home>/programs/<identifier>

set_program_command()

FIXME: working directory is relative to <home>/programs/<identifier>/bin

get_program_command()

FIXME: working directory is relative to <home>/programs/<identifier>/bin

set_program_stdio_redirection()

FIXME: stdio file names are relative to <home>/programs/<identifier>/bin

get_program_stdio_redirection()

FIXME: stdio file names are relative to <home>/programs/<identifier>/bin

set_program_schedule()
get_program_schedule()
get_program_scheduler_state()

FIXME: message is currently valid in error-occurred state only

continue_program_schedule()
start_program()
get_last_spawned_program_process()
get_custom_program_option_names()
set_custom_program_option_value()
get_custom_program_option_value()
remove_custom_program_option()
get_identity()

Returns the UID, the UID where the Brick is connected to, the position, the hardware and firmware version as well as the device identifier.

The position is the position in the stack from '0' (bottom) to '8' (top).

The device identifier numbers can be found :ref:`here <device_identifier>`. |device_identifier_constant|