Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Common/Cpp/Options/BatchOption.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,9 @@ FixedLimitVector<ConfigOption*> BatchOption::options() const{
}
return ret;
}
const std::vector<std::pair<ConfigOption*, std::string>>& keyed_options(const BatchOption& batch){
return batch.m_data->m_options;
}



Expand Down
11 changes: 11 additions & 0 deletions Common/Cpp/Options/BatchOption.h
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@
#ifndef PokemonAutomation_Options_BatchOption_H
#define PokemonAutomation_Options_BatchOption_H

#include <string>
#include <utility>
#include <vector>
#include "Common/Cpp/Containers/Pimpl.h"
#include "Common/Cpp/Containers/FixedLimitVector.h"
#include "ConfigOption.h"
Expand Down Expand Up @@ -42,6 +45,8 @@ class BatchOption : public UiState<BatchOption, ConfigOption>{
bool horizontal() const;
FixedLimitVector<ConfigOption*> options() const;

friend const std::vector<std::pair<ConfigOption*, std::string>>& keyed_options(const BatchOption& batch);


private:
struct Data;
Expand All @@ -51,5 +56,11 @@ class BatchOption : public UiState<BatchOption, ConfigOption>{



// Each option of `batch` with the key it is saved under in to_json(), in the
// order they were added. Static options have an empty key.
const std::vector<std::pair<ConfigOption*, std::string>>& keyed_options(const BatchOption& batch);



}
#endif
32 changes: 31 additions & 1 deletion SerialPrograms/Source/CommonFramework/Windows/Lab.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,7 @@ program.
| `start [SECONDS]` | What clicking Start Program does. Refused unless the program is `STOPPED`. First waits up to `SECONDS` (default 30) for `controller=ready`, and refuses with `controller not connected` if it never is, instead of starting a program that would fail with "Incompatible Controller". |
| `stop` | What clicking Stop Program does. Refused unless the program is `RUNNING`. The request goes on; the program stops in the background. |
| `state` | Prints the state file's lines into the journal. (In the Command File Runner program, `state [image]` prints the detectors that fire instead; from the channel use `detect` per detector.) |
| `describe_program` | Prints the selected program's id and the static contract of its options as one line, `describe_program <JSON>`; see [Describe program](#describe-program). Reads only: needs no owner token and no console. Refused when the selected panel is not a program. |
| `snapshot LABEL [TIMEOUT_MS]` | Saves the first video frame newer than this line as `<request>_<LABEL>.png` and names it; see [Snapshot](#snapshot). Reads only: needs no owner token, no program state and no controller. |
| `keepawake on\|off [seconds]` | While it is on and no program runs, presses B every `seconds` (default 15) so the console does not sleep. A running program pauses it. Off by default; off again when the app restarts. |
| `popups [close]` | Lists the app's open message boxes (title and text), such as the "Error" box a failed program leaves. `close` presses each one's default button. |
Expand All @@ -122,7 +123,7 @@ program.

These run on the selected program's console. A press runs only while no
program runs (`STOPPED`); the commands that only read the screen (`shot`,
`shots`, `history`, `detect`, `wait_for`, `expect`) run any time.
`shots`, `history`, `detect`, `wait_for`, `expect`, `game_open`) run any time.

#### Controller

Expand All @@ -142,6 +143,7 @@ program runs (`STOPPED`); the commands that only read the screen (`shot`,
| `shot label` | Saves the current frame as `<request>_<label>.png` in the outbox. | |
| `shots label count [interval]` | Saves `count` frames, `<label>_0` to `<label>_<count-1>`, one every `interval`. | interval 500 |
| `history label` | Saves the console's recent video as `<request>_<label>.mp4` in the outbox, when Stream History is on. Run it right after a program to keep a recording of that run. | |
| `game_open [image]` | Prints `game_open yes` when a game is in front, or `game_open no REASON` with `REASON` `home` (the Home menu), `user_select` ("Who is using the software?"), `black` (a black screen: loading, or no signal) or `no_video`. It does not tell one game from another. Never fails the line. With `image`, it checks a saved picture, as `detect` does. | |
| `detect detector [image]` | Runs a detector once and prints `yes` or `no`. With `image`, it runs on a saved picture instead of the live video: an absolute path, or a file name in the outbox. | |
| `wait_for detector [timeout]` | Checks the video every 100 ms until the detector fires. Prints how long it took, or `timeout`. | timeout 5000 |
| `expect detector [timeout]` | The same as `wait_for`, but a timeout fails the line. | timeout 5000 |
Expand Down Expand Up @@ -194,6 +196,34 @@ ok 2 snapshot frame 2000 @0-41ms
end
```

### Describe program

`describe_program` tells the lab server what the selected program takes,
without running it or touching the console. The JSON (version 1, keys
sorted):

```
describe_program {"id":"PokemonFRLG:AutoStory","options":[...],"prechecks":"unsupported","schema":1}
```

- `id`: the program's identifier, as `select` takes it.
- `options`: one entry per option the settings file saves, in the order the
program shows them. Each has `key` (what `set` takes; a group's options
are under the group's key, so `set GROUP.KEY`), `type`, and by type:

| `type` | Fields |
|---|---|
| `boolean`, `string` | `default` |
| `integer`, `number` | `default`, `min`, `max` (`null` when a number has no bound) |
| `enum`, `select` | `default` and `entries`, each `{"slug", "enabled"}`; `set` takes the slug |
| `group` | `toggleable` (it has its own `Enabled` key) and its own `options` |
| `other` | nothing yet: the contract does not describe that type |

The defaults are the program's defaults, not the values it holds now.
Which options show and whether a combination is valid depend on the other
options' values; they are not part of the contract.
- `prechecks`: `unsupported` until the program declares a precheck list.

## Owner

Two scripts driving one console would interleave their presses. A script
Expand Down
24 changes: 24 additions & 0 deletions SerialPrograms/Source/CommonFramework/Windows/LabChannel.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
#include "CommonFramework/Tools/GlobalThreadPools.h"
#include "CommonFramework/VideoPipeline/Backends/VideoFrameQt.h"
#include "LabChannel.h"
#include "LabProgramContract.h"
#include "LabSnapshot.h"

namespace PokemonAutomation{
Expand Down Expand Up @@ -79,6 +80,7 @@ void print_channel_help(std::ostream& out){
" start [SECONDS] | stop (start waits up to SECONDS, default 30, for the controller)\n"
" state\n"
" snapshot LABEL [TIMEOUT_MS] (saves the first video frame newer than the call; default 5000 ms)\n"
" describe_program (the selected program's id and option contract, as one line of JSON)\n"
" keepawake on|off [seconds]\n"
" popups [close] (the app's message boxes; close presses their default button)\n help\n";
}
Expand Down Expand Up @@ -423,6 +425,9 @@ std::string LabChannel::run_line(const LabRequest& request, const LabRequestLine
if (command == "snapshot"){
return run_snapshot(words, output);
}
if (command == "describe_program"){
return run_describe_program(words, output.out);
}
const LabConsoleCommands::Kind kind = m_console->kind(command);
if (kind != LabConsoleCommands::Kind::READS_STREAM){
std::string error = m_owner.check(request.owner);
Expand All @@ -442,6 +447,25 @@ std::string LabChannel::run_line(const LabRequest& request, const LabRequestLine
return run_console_command(words, output);
}

// "describe_program": the selected program's id and the static contract of
// its options (LabProgramContract.h), as one line of JSON. Reads only.
std::string LabChannel::run_describe_program(const std::vector<std::string>& words, std::ostream& out){
if (words.size() != 1){
return "describe_program: expected describe_program";
}
std::lock_guard<Mutex> lg(m_panel_lock);
if (m_panel == nullptr || m_program == nullptr){
return "describe_program: the selected panel is not a program.";
}
const BatchOption* options = m_console->options(*m_panel);
if (options == nullptr){
return "describe_program: the selected program has no options the lab can read.";
}
JsonValue contract = lab_program_contract(m_program->descriptor().identifier(), *options);
out << "describe_program " << contract.dump(-1) << "\n";
return "";
}

std::string LabChannel::run_console_command(const std::vector<std::string>& words, LabCommandOutput& output){
const bool reads_only = m_console->kind(words[0]) == LabConsoleCommands::Kind::READS_STREAM;
return run_on_console([&](PanelSession& panel, CancellableScope& scope){
Expand Down
6 changes: 6 additions & 0 deletions SerialPrograms/Source/CommonFramework/Windows/LabChannel.h
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
#include "Common/Cpp/Concurrency/AsyncTask.h"
#include "Common/Cpp/Concurrency/Mutex.h"
#include "Common/Cpp/Concurrency/ConditionVariable.h"
#include "Common/Cpp/Options/BatchOption.h"
#include "CommonFramework/Globals.h"
#include "CommonFramework/Panels/PanelSession.h"
#include "CommonFramework/ProgramSession.h"
Expand Down Expand Up @@ -104,6 +105,10 @@ class LabConsoleCommands{
// Called on the UI thread.
virtual VideoFeed* video(PanelSession& panel) = 0;

// The options of the program `panel`, or nullptr if it is not a program
// of this console type. Read by "describe_program".
virtual const BatchOption* options(PanelSession& panel) = 0;

// The press that keeps the console awake ("keepawake on").
virtual void keep_awake(PanelSession& panel, CancellableScope& scope) = 0;

Expand Down Expand Up @@ -146,6 +151,7 @@ class LabChannel{
std::string run_start(const LabRequest& request, const std::vector<std::string>& words);
std::string run_popups(const std::vector<std::string>& words, std::ostream& out);
std::string run_snapshot(const std::vector<std::string>& words, LabCommandOutput& output);
std::string run_describe_program(const std::vector<std::string>& words, std::ostream& out);
std::string run_on_ui(const std::function<std::string()>& body);
void keep_awake();
void write_state();
Expand Down
166 changes: 166 additions & 0 deletions SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
/* Lab Program Contract
*
* From: https://github.com/PokemonAutomation/
*
*/

#include <limits>
#include <optional>
#include <string>
#include "Common/Cpp/Json/JsonValue.h"
#include "Common/Cpp/Options/BooleanCheckBoxOption.h"
#include "Common/Cpp/Options/EnumDropdownOption.h"
#include "Common/Cpp/Options/FloatingPointOption.h"
#include "Common/Cpp/Options/GroupOption.h"
#include "Common/Cpp/Options/SimpleIntegerOptionBase.h"
#include "Common/Cpp/Options/StringOption.h"
#include "CommonTools/Options/StringSelectOption.h"
#include "LabProgramContract.h"

namespace PokemonAutomation{


namespace{

// A floating-point bound, or null for the "no bound" default.
JsonValue number_bound(double bound){
if (bound <= -std::numeric_limits<double>::max() || bound >= std::numeric_limits<double>::max()){
return JsonValue();
}
return bound;
}

JsonArray enum_entries(const IntegerEnumDropdownDatabase& database){
JsonArray entries;
for (size_t value : database.all_values()){
const EnumEntry* entry = database.find(value);
JsonObject item;
item["slug"] = entry->slug;
item["enabled"] = entry->enabled;
entries.push_back(std::move(item));
}
return entries;
}

JsonArray select_entries(const StringSelectDatabase& database){
JsonArray entries;
for (const StringSelectEntry& entry : database.case_list()){
JsonObject item;
item["slug"] = entry.slug;
item["enabled"] = true;
entries.push_back(std::move(item));
}
return entries;
}

// A group's "type" and options. Nothing if `option` is not a group.
std::optional<JsonObject> describe_group(const ConfigOption& option){
JsonObject out;
const BatchOption* batch = dynamic_cast<const BatchOption*>(&option);
if (batch == nullptr){
return std::nullopt;
}
const GroupOption* group = dynamic_cast<const GroupOption*>(&option);
out["type"] = "group";
out["toggleable"] = group != nullptr && group->toggleable();
out["options"] = lab_option_contract(*batch);
return out;
}

// A boolean's, number's or string's "type", "default" and bounds. Nothing
// if `option` is none of them.
std::optional<JsonObject> describe_value(const ConfigOption& option){
JsonObject out;
if (const BooleanCheckBoxCell* cell = dynamic_cast<const BooleanCheckBoxCell*>(&option)){
out["type"] = "boolean";
out["default"] = cell->default_value();
return out;
}
if (const SimpleIntegerCellBase* cell = dynamic_cast<const SimpleIntegerCellBase*>(&option)){
out["type"] = "integer";
out["default"] = cell->default_value();
out["min"] = cell->min_value();
out["max"] = cell->max_value();
return out;
}
if (const FloatingPointCell* cell = dynamic_cast<const FloatingPointCell*>(&option)){
out["type"] = "number";
out["default"] = cell->default_value();
out["min"] = number_bound(cell->min_value());
out["max"] = number_bound(cell->max_value());
return out;
}
if (const StringCell* cell = dynamic_cast<const StringCell*>(&option)){
out["type"] = "string";
out["default"] = cell->default_value();
return out;
}
return std::nullopt;
}

// A choice's "type", "default" and "entries". Nothing if `option` is not a
// choice.
std::optional<JsonObject> describe_choice(const ConfigOption& option){
JsonObject out;
if (const IntegerEnumDropdownCell* cell = dynamic_cast<const IntegerEnumDropdownCell*>(&option)){
const IntegerEnumDropdownDatabase& database = cell->database();
out["type"] = "enum";
out["default"] = database.find(cell->default_value())->slug;
out["entries"] = enum_entries(database);
return out;
}
if (const StringSelectCell* cell = dynamic_cast<const StringSelectCell*>(&option)){
out["type"] = "select";
out["default"] = cell->default_slug();
out["entries"] = select_entries(cell->database());
return out;
}
return std::nullopt;
}

// The fields of `option` for its entry: "type" and those of that type.
JsonObject describe_option(const ConfigOption& option){
std::optional<JsonObject> described = describe_group(option);
if (!described){
described = describe_value(option);
}
if (!described){
described = describe_choice(option);
}
if (described){
return std::move(*described);
}
JsonObject other;
other["type"] = "other";
return other;
}

} // namespace



JsonArray lab_option_contract(const BatchOption& options){
JsonArray contract;
for (const auto& item : keyed_options(options)){
if (item.second.empty()){
continue;
}
JsonObject entry = describe_option(*item.first);
entry["key"] = item.second;
contract.push_back(std::move(entry));
}
return contract;
}

JsonObject lab_program_contract(std::string_view id, const BatchOption& options){
JsonObject contract;
contract["schema"] = LAB_PROGRAM_CONTRACT_SCHEMA;
contract["id"] = std::string(id);
contract["options"] = lab_option_contract(options);
contract["prechecks"] = "unsupported";
return contract;
}



} // namespace PokemonAutomation
47 changes: 47 additions & 0 deletions SerialPrograms/Source/CommonFramework/Windows/LabProgramContract.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
/* Lab Program Contract
*
* From: https://github.com/PokemonAutomation/
*
* What "describe_program" tells the lab server about a program without
* touching its console: its id and the static contract of its options.
* Each option with a key gets its key (the one "set" takes), its type, its
* default, and for numbers its bounds, for choices its entries and which of
* them are enabled. What depends on other options' values (visibility,
* check_validity()) is not part of it; the lab server checks that later on
* the loaded options.
*
* The shape is version 1 of the lab server's program contract, in
* docs/design/Agent-Integration.md ("Program contract and preflight").
*
*/

#ifndef PokemonAutomation_LabProgramContract_H
#define PokemonAutomation_LabProgramContract_H

#include <string_view>
#include "Common/Cpp/Json/JsonArray.h"
#include "Common/Cpp/Json/JsonObject.h"
#include "Common/Cpp/Options/BatchOption.h"

namespace PokemonAutomation{


// The version of the reply below.
constexpr int LAB_PROGRAM_CONTRACT_SCHEMA = 1;

// One entry per option of `options` that has a key, in the order they were
// added: {"key", "type", ...}. Types: "boolean", "integer" and "number"
// (with "min" and "max", null when unbounded), "string", "enum" and
// "select" (with "entries": {"slug", "enabled"}), "group" (with its own
// "options", and "toggleable"), and "other" for a type the contract does
// not describe yet. Every type but "group" and "other" has a "default".
JsonArray lab_option_contract(const BatchOption& options);

// The whole reply: {"schema", "id", "options", "prechecks"}. `prechecks`
// is "unsupported" until the program declares a precheck list.
JsonObject lab_program_contract(std::string_view id, const BatchOption& options);



} // namespace PokemonAutomation
#endif
Loading
Loading