bus — различия между версиями
Manticora (обсуждение | вклад) (Новая страница: «;bus [boolean] :Эта системная переменная определяет, включить ли бус-шину (англ. bus), которая позво…») |
4epT (обсуждение | вклад) (→Windows ОС) |
||
(не показано 5 промежуточных версий этого же участника) | |||
Строка 1: | Строка 1: | ||
− | ;bus [ | + | ; bus [<[[References#булев_флаг|булев_флаг]]>] |
− | : | + | : Данная переменная позволяет подключаться к bus-шине при старте OpenKore. Если bus-сервер не найден, то он создаётся автоматически. Настройки bus-сервера задаются параметрами: [[bus_server_host]], [[bus_server_port]] и [[bus_userAgent]]. |
− | == Коротко о | + | == Коротко о bus-шине == |
− | + | bus-шина - это специальный протокол, который позволяет различным экземплярам OpenKore легко общаться между собой. Также внешние программы через bus-шину могут общаться с подключенными к ней OpenKore. | |
− | + | bus-шина использует канал связи, который позволяет передавать широковещательные и приватные сообщения. Широковещательные сообщения получат все экземпляры OpenKore, которые подключены к этой шине. Приватное сообщение получит только одна версия OpenKore. Bus можно сравнить с любым мессенджером, где люди могут общаться как в открытых каналах, так и в приватных комнатах. | |
+ | |||
+ | bus-шина основана на отдельных сообщениях, вместо непрерывной отправки цепочки байт. | ||
+ | |||
+ | [[Файл:bus.png]] | ||
+ | |||
+ | == Запуск bus-сервера == | ||
+ | |||
+ | Существует два метода запуска bus-сервера: | ||
+ | * автоматически запускать его с помощью вашего (первого) экземпляра OpenKore, если настроены соответствующие параметры в sys.txt | ||
+ | * вручную, из командной строки | ||
+ | |||
+ | |||
+ | '''Сценарии''' | ||
+ | * на одном компе с несколькими запущенными экземплярами OpenKore первый экземпляр запустит bus-сервер. Все остальные экземпляры будут проверять номер порта и подключаться к тому же bus-серверу. | ||
+ | * если экземпляры OpenKore запускаются на разных компах, то следует вручную запустить bus-сервер, указав определённый порт. Это позволит всем экземплярам OpenKore (сценариям Perl или автономным программам) подключаться к одному и тому же bus-серверу. | ||
+ | |||
+ | |||
+ | === Автозапуск bus—сервера === | ||
+ | |||
+ | Автозапуск bus-сервера работает одинаково на всех поддерживаемых ОС. | ||
+ | |||
+ | Просто настройте <code>bus 1</code> в [[sys.txt]] для всех экземпляров OpenKore.Первый загруженный экземпляр запустит bus-сервер. | ||
+ | |||
+ | '''Варианты использования:''' | ||
+ | * один комп, много экземпляров OpenKore | ||
+ | * один комп, один или несколько экземпляров OpenKore, один или несколько автономных Perl скриптов с поддержкой bus-шины запущены на одном компе | ||
+ | |||
+ | === Запуск bus-сервера вручную === | ||
+ | |||
+ | Ручной запуск - это лучшее решение при использовании нескольких компов в следующих сценариях: | ||
+ | * экземпляры OpenKore работают на нескольких компьютерах | ||
+ | * используются автономные perl скрипты, которые запускаются до загрузки OpenKore | ||
+ | |||
+ | В этих случаях, для разрешения различным программам подключаться к bus-серверу, сервер должен быть запущен на заранее заданном хосте и порту. | ||
+ | Ниже подробно описаны параметры командной строки и способы загрузки bus-сервера. | ||
+ | |||
+ | ==== Параметры командной строки ==== | ||
+ | |||
+ | Параметры командной строки можно увидеть, запустив скрипт bus-сервера с ключом <code>--help</code> | ||
+ | |||
+ | {| class="wikitable" border="1" cellspacing="0" | ||
+ | |-style=background-color:#F9F9F9; | ||
+ | !Параметр | ||
+ | !Описание | ||
+ | |- | ||
+ | |align=center|--bind=<host> | ||
+ | |укажите имя хоста или IP-адрес, который будет прослушивать bus-сервер. Это эквивалент параметра [[bus_server_host]] в sys.txt | ||
+ | |- | ||
+ | |align=center|--port=<номер_порт> | ||
+ | |Запустить bus-сервер на специальном порту. Если этот параметр пустой, то будет выбран первый доступный порт. Допустимый диапазон: от 1 до 65535. | ||
+ | |- | ||
+ | |align=center|--quiet | ||
+ | |НЕ выводить статусные сообщения | ||
+ | |- | ||
+ | |align=center|--help | ||
+ | |Показать справку обо всех параметрах | ||
+ | |} | ||
+ | |||
+ | |||
+ | ==== Windows ОС==== | ||
+ | |||
+ | Большинство пользователей OpenKore в Windows используют для запуска бота консоль (start.exe) или графический [[Wx_интерфейс]] (wxstart.exe). | ||
+ | |||
+ | Чтобы запустить bus-сервер с указанным портом, используйте соответствующую команду: | ||
+ | |||
+ | <b>Консоль:</b><code>start.exe "!" "src/Bus/bus-server.pl" --port=1337</code> | ||
+ | |||
+ | <b>Wx интерфейс:</b><code>wxstart.exe "!" "src/Bus/bus-server.pl" --port=54321</code> | ||
+ | |||
+ | Пользователи могут либо создать свои bat скрипты, либо изменить ярлык запуска исполняемый файл OpenKore с этими аргументами. | ||
+ | |||
+ | При старте bus-сервера во временной папке "AppData\Local\Temp\" создаётся файл с описанием параметров сервера '''OpenKore-Bus.info''' | ||
+ | |||
+ | ==== Unix ОС / OpenKore запускается в интерпретаторе perl ==== | ||
+ | |||
+ | Вы можете запустить bus-сервер из каталога, где находится openkore.pl: | ||
+ | <code>yourlogin ~> ./src/Bus/bus-server.pl --port=31416</code> | ||
− | |||
== Описание протокола == | == Описание протокола == | ||
Строка 15: | Строка 91: | ||
Каждое сообщение SSM содержит следующую информацию: | Каждое сообщение SSM содержит следующую информацию: | ||
− | * | + | * идентификатор сообщения - MID. Это строка, в которой может быть написано всё, что угодно. |
− | * | + | * список аргументов. Это может быть либо список пар вида параметр-значение (хэш), либо список скалярных значений (массив). |
− | + | Сообщения очень похожи на вызов функции в языках программирования. Представьте себе следующую функцию в C++: | |
void copyFile(string from, string to); | void copyFile(string from, string to); | ||
copyFile("foo.txt", "bar.txt"); | copyFile("foo.txt", "bar.txt"); | ||
− | Проводя аналогию между функцией на C++ и сообщением SSM для | + | Проводя аналогию между функцией на C++ и сообщением SSM для bus-шины, можно отметить: |
− | * | + | * идентификатор сообщения был бы строкой '''copyFile'''; |
− | * | + | * список аргументов состоял бы из двух пар параметр-значение: |
from = foo.txt | from = foo.txt | ||
to = bar.txt | to = bar.txt | ||
Строка 31: | Строка 107: | ||
=== Структура сообщения === | === Структура сообщения === | ||
− | + | Примечание: все целые числа записываются в [https://ru.wikipedia.org/wiki/%D0%9F%D0%BE%D1%80%D1%8F%D0%B4%D0%BE%D0%BA_%D0%B1%D0%B0%D0%B9%D1%82%D0%BE%D0%B2 big-endian]. Это означает, что в сообщении старший байт будет записан перед младшим. | |
=== Заголовок сообщения === | === Заголовок сообщения === | ||
Строка 39: | Строка 115: | ||
struct { | struct { | ||
// Header | // Header | ||
− | uint32 length; // | + | uint32 length; // длина всего SSM-сообщения в байтах |
− | uint8 options; // | + | uint8 options; // тип SSM-сообщения: 0 = список пар параметр-значение, 1 = список скаляров (массив) |
− | uint8 MID_length; // | + | uint8 MID_length; // длина MID - идентификатора сообщения |
− | char MID[MID_length]; // MID - идентификатор сообщения | + | char MID[MID_length]; // MID - идентификатор сообщения (UTF-8 строка) |
} Header; | } Header; | ||
− | Если в | + | Если в заголовке сообщения поле '''options = 0''', тогда после заголовка следует список структур '''struct MapEntry''', который идёт до конца SSM-сообщения. Это список пар параметр-значение. |
− | Если | + | Если в заголовке сообщения поле '''options = 1''', тогда после заголовка следует список структур '''struct ArrayEntry''', который идёт до конца SSM-сообщения. Это список скаляров (массив). |
− | + | === Структура параметр-значение === | |
struct { | struct { | ||
− | uint8 key_length; // | + | uint8 key_length; // длина имени параметра |
− | char key[key_length]; // | + | char key[key_length]; // имя параметра (UTF-8 строка) |
− | uint8 value_type; // | + | uint8 value_type; // тип значения: 0 = двоичный, 1 = UTF-8 строка, 2 = unsigned integer |
− | uint24 value_length; // | + | uint24 value_length; // длина значения |
− | char value[value_length]; // | + | char value[value_length]; // само значения |
} MapEntry; | } MapEntry; | ||
− | + | === Структура массива === | |
struct { | struct { | ||
− | uint8 type; // | + | uint8 type; // по аналогии MapEntry.value_type |
− | uint24 length; | + | uint24 length; |
− | char value[length]; | + | char value[length]; |
} ArrayEntry; | } ArrayEntry; | ||
[[Category:sys.txt]] | [[Category:sys.txt]] |
Текущая версия на 22:50, 9 июля 2021
- bus [<булев_флаг>]
- Данная переменная позволяет подключаться к bus-шине при старте OpenKore. Если bus-сервер не найден, то он создаётся автоматически. Настройки bus-сервера задаются параметрами: bus_server_host, bus_server_port и bus_userAgent.
Коротко о bus-шине
bus-шина - это специальный протокол, который позволяет различным экземплярам OpenKore легко общаться между собой. Также внешние программы через bus-шину могут общаться с подключенными к ней OpenKore.
bus-шина использует канал связи, который позволяет передавать широковещательные и приватные сообщения. Широковещательные сообщения получат все экземпляры OpenKore, которые подключены к этой шине. Приватное сообщение получит только одна версия OpenKore. Bus можно сравнить с любым мессенджером, где люди могут общаться как в открытых каналах, так и в приватных комнатах.
bus-шина основана на отдельных сообщениях, вместо непрерывной отправки цепочки байт.
Запуск bus-сервера
Существует два метода запуска bus-сервера:
- автоматически запускать его с помощью вашего (первого) экземпляра OpenKore, если настроены соответствующие параметры в sys.txt
- вручную, из командной строки
Сценарии
- на одном компе с несколькими запущенными экземплярами OpenKore первый экземпляр запустит bus-сервер. Все остальные экземпляры будут проверять номер порта и подключаться к тому же bus-серверу.
- если экземпляры OpenKore запускаются на разных компах, то следует вручную запустить bus-сервер, указав определённый порт. Это позволит всем экземплярам OpenKore (сценариям Perl или автономным программам) подключаться к одному и тому же bus-серверу.
Автозапуск bus—сервера
Автозапуск bus-сервера работает одинаково на всех поддерживаемых ОС.
Просто настройте bus 1
в sys.txt для всех экземпляров OpenKore.Первый загруженный экземпляр запустит bus-сервер.
Варианты использования:
- один комп, много экземпляров OpenKore
- один комп, один или несколько экземпляров OpenKore, один или несколько автономных Perl скриптов с поддержкой bus-шины запущены на одном компе
Запуск bus-сервера вручную
Ручной запуск - это лучшее решение при использовании нескольких компов в следующих сценариях:
- экземпляры OpenKore работают на нескольких компьютерах
- используются автономные perl скрипты, которые запускаются до загрузки OpenKore
В этих случаях, для разрешения различным программам подключаться к bus-серверу, сервер должен быть запущен на заранее заданном хосте и порту. Ниже подробно описаны параметры командной строки и способы загрузки bus-сервера.
Параметры командной строки
Параметры командной строки можно увидеть, запустив скрипт bus-сервера с ключом --help
Параметр | Описание |
---|---|
--bind=<host> | укажите имя хоста или IP-адрес, который будет прослушивать bus-сервер. Это эквивалент параметра bus_server_host в sys.txt |
--port=<номер_порт> | Запустить bus-сервер на специальном порту. Если этот параметр пустой, то будет выбран первый доступный порт. Допустимый диапазон: от 1 до 65535. |
--quiet | НЕ выводить статусные сообщения |
--help | Показать справку обо всех параметрах |
Windows ОС
Большинство пользователей OpenKore в Windows используют для запуска бота консоль (start.exe) или графический Wx_интерфейс (wxstart.exe).
Чтобы запустить bus-сервер с указанным портом, используйте соответствующую команду:
Консоль:start.exe "!" "src/Bus/bus-server.pl" --port=1337
Wx интерфейс:wxstart.exe "!" "src/Bus/bus-server.pl" --port=54321
Пользователи могут либо создать свои bat скрипты, либо изменить ярлык запуска исполняемый файл OpenKore с этими аргументами.
При старте bus-сервера во временной папке "AppData\Local\Temp\" создаётся файл с описанием параметров сервера OpenKore-Bus.info
Unix ОС / OpenKore запускается в интерпретаторе perl
Вы можете запустить bus-сервер из каталога, где находится openkore.pl:
yourlogin ~> ./src/Bus/bus-server.pl --port=31416
Описание протокола
Создатель этого протокола назвал формат сообщений "Simple Serializable Message" (SSM). Формат этих сообщений - двоичный.
Каждое сообщение SSM содержит следующую информацию:
- идентификатор сообщения - MID. Это строка, в которой может быть написано всё, что угодно.
- список аргументов. Это может быть либо список пар вида параметр-значение (хэш), либо список скалярных значений (массив).
Сообщения очень похожи на вызов функции в языках программирования. Представьте себе следующую функцию в C++:
void copyFile(string from, string to); copyFile("foo.txt", "bar.txt");
Проводя аналогию между функцией на C++ и сообщением SSM для bus-шины, можно отметить:
- идентификатор сообщения был бы строкой copyFile;
- список аргументов состоял бы из двух пар параметр-значение:
from = foo.txt to = bar.txt
Структура сообщения
Примечание: все целые числа записываются в big-endian. Это означает, что в сообщении старший байт будет записан перед младшим.
Заголовок сообщения
Каждое SSM-сообщение начинается с заголовка struct Header, структура которого описана ниже:
struct { // Header uint32 length; // длина всего SSM-сообщения в байтах uint8 options; // тип SSM-сообщения: 0 = список пар параметр-значение, 1 = список скаляров (массив) uint8 MID_length; // длина MID - идентификатора сообщения char MID[MID_length]; // MID - идентификатор сообщения (UTF-8 строка) } Header;
Если в заголовке сообщения поле options = 0, тогда после заголовка следует список структур struct MapEntry, который идёт до конца SSM-сообщения. Это список пар параметр-значение.
Если в заголовке сообщения поле options = 1, тогда после заголовка следует список структур struct ArrayEntry, который идёт до конца SSM-сообщения. Это список скаляров (массив).
Структура параметр-значение
struct { uint8 key_length; // длина имени параметра char key[key_length]; // имя параметра (UTF-8 строка) uint8 value_type; // тип значения: 0 = двоичный, 1 = UTF-8 строка, 2 = unsigned integer uint24 value_length; // длина значения char value[value_length]; // само значения } MapEntry;
Структура массива
struct { uint8 type; // по аналогии MapEntry.value_type uint24 length; char value[length]; } ArrayEntry;