bus
- bus [boolean]
- Enables bus system.
About the bus system
The bus system's goal is to allow different OpenKore instances to easily communicate with each other, and to allow external tools to easily communicate with a running OpenKore instance.
The bus is a communication channel which supports broadcast communication as well as private communication. One can compare it to an open street: anyone can shout a message to everybody (broadcast communication) or whisper a message into someone else's ears (private communication).
Furthermore, the bus system is based on discrete messages instead of byte streams.
Examples of using the Bus
$messageID
is a string identifier (name) for the message.
$args
can be either a reference to a hash or an array that contains only scalar (string or numeric) value's. Which implies that it cannot be a complex datatype.
Send a message in OpenKore
use Globals qw($bus);
if ($bus->getState == Bus::Client::CONNECTED) { $bus->send($messageID, $args); }
- If you do not check for CONNECTED, your message will be queued and it will be sent when the Bus connects.
Receive a message in OpenKore
use Globals qw($bus); my $on_message_received;
Load:
sub bus_message_received { my (undef, undef, $message) = @_; if ($message->{messageID} eq $messageID) { # that's a message we're interested with (having $messageID name) # $args is at $message->{args} } } $on_message_received = $bus->onMessageReceived->add(undef, \&bus_message_received);
Unload:
$bus->onMessageReceived->remove($on_message_received);
Standalone script
Everything is the same, you just need to start the Bus and iterate it in your main loop.
use lib '<path to OpenKore src dir>'; use Bus::Client; use Bus::Handlers; use constant BUS_USER_AGENT => 'Meaningful name of your script'; # use this to connect to local bus server, otherwise specify host and port my $bus = new Bus::Client(host => undef, port => undef, userAgent => BUS_USER_AGENT); my $bus_message_handlers = new Bus::Handlers($bus); # (add here listener for receiving Bus messages, if needed) while () { # (add here your code, and send Bus messages, if needed) $bus->iterate; sleep 1; }
Protocol description
I call the message format the "Simple Serializable Message" (SSM). This message format is binary.
A message contains the following information:
- A message identifier (MID). This is a string, which can be anything.
- A list of arguments. This is either a list of key-value pairs (a key-value map), or a list of scalars (an array).
A message is very comparable to a function call. Imagine the following C++ function:
void copyFile(string from, string to); copyFile("foo.txt", "bar.txt");
- The message ID would be "copyFile".
- The key/value pairs would look like this:
from = foo.txt to = bar.txt
Message structure
Note that all integers are big-endian.
Header
Each message starts with a header:
struct { // Header uint32 length; // The length of the entire message, in bytes. uint8 options; // The message type: 0 = key-value map, 1 = array. uint8 MID_length; // The message ID's length. char MID[MID_length]; // The message ID, as a UTF-8 string. } Header;
If options is set to 0, then what comes after the header is a list of MapEntry structures, until the end of the message.
If options is set to 1, then what comes after the header is a list of ArrayEntry structures, until the end of the message.
Key-value map entry
struct { uint8 key_length; // Length of the key. char key[key_length]; // UTF-8 string. uint8 value_type; // Value type: 0 = binary, 1 = UTF-8 string, 2 = unsigned integer uint24 value_length; // Length of the value. char value[value_length]; // The value data. } MapEntry;
Array entry
struct { uint8 type; // Like MapEntry.value_type uint24 length; char value[length]; } ArrayEntry;