diff --git a/Documentation/Changelog.md b/Documentation/Changelog.md index 6bc275bac..b42326438 100644 --- a/Documentation/Changelog.md +++ b/Documentation/Changelog.md @@ -4,6 +4,12 @@ ## v1.6.5 +### `tdw` module + +#### `Controller` + +- Removed optional `display` parameter. It doesn't actually work; Linux users should instead launch the controller with a `DISPLAY` environment variable. + ### Frontend - Added `freeze.py`. "Freeze" your controller into a portable binary executable. @@ -21,6 +27,12 @@ | ----------- | ------------------------------------------------------------ | | `freeze.md` | How to freeze your controller code into a binary executable. | +#### Modified Documentation + +| Document | Description | +| -------------------- | ---------------------------------------------------------- | +| `getting_started.md` | Fixed instructions for how to start a controller in Linux. | + ## v1.6.4 ### `tdw` module diff --git a/Documentation/getting_started.md b/Documentation/getting_started.md index d8a5ef8ab..aac049130 100644 --- a/Documentation/getting_started.md +++ b/Documentation/getting_started.md @@ -40,7 +40,7 @@ TDW is a general-purpose tool that allows the user to communicate and manipulate ##### 2a. On a personal computer: -Create this Python script and run it: +1. Create this Python script and save it as `my_controller.py`: ```python from tdw.controller import Controller @@ -50,6 +50,14 @@ print("Everything is OK!") c.communicate({"$type": "terminate"}) ``` +2. Run the controller: + +| Windows | OS X | Linux | +| ------------------------ | -------------------------- | --------------------------------------- | +| `py -3 my_controller.py` | `python3 my_controller.py` | `DISPLAY=:0.0 python3 my_controller.py` | + +Note for Linux users: You only need to include `DISPLAY` if the [launch_build parameter in the Controller constructor](python/controller.md) is set to False (by default, it is True). + When you launch run this script, the `Controller` will download the **build**, the binary executable application that runs the simulation environment and then launch the build. The controller will also check to see if your version of TDW is the most recent. For more information on what happens when you start a controller, read [this](misc_frontend/releases.md#Updates). ##### 2b. On a remote Linux server: @@ -65,17 +73,22 @@ sudo /usr/bin/X :0& NOTE: Not all of these commands will be applicable to every server. The last number is the `display_number` which will be used in the script below: -2. Create this Python script and run it: +2. Create this Python script and save it as `my_controller.py`: ```python from tdw.controller import Controller -display_number = 0 # Set this number to your virtual display. -c = Controller(display=display_number) +c = Controller() print("Everything is OK!") c.communicate({"$type": "terminate"}) ``` +3. Run the controller: + +```bash +DISPLAY=:0.0 python3 my_controller.py # Your display number might not be 0 +``` + ##### 2c. From a Docker container: Read [this](https://github.com/threedworld-mit/tdw/blob/v1.6.1/Documentation/Docker/docker.md). We recommend first trying TDW on a personal computer to familiarize yourself with the basic setup. diff --git a/Documentation/python/controller.md b/Documentation/python/controller.md index 4402849f0..8315c4970 100644 --- a/Documentation/python/controller.md +++ b/Documentation/python/controller.md @@ -16,7 +16,7 @@ c.start() *** -#### `__init__(self, port: int = 1071, check_version: bool = True, launch_build: bool = True, display: int = None)` +#### `__init__(self, port: int = 1071, check_version: bool = True, launch_build: bool = True)` Create the network socket and bind the socket to the port. @@ -25,7 +25,6 @@ Create the network socket and bind the socket to the port. | port | The port number. | | check_version | If true, the controller will check the version of the build and print the result. | | launch_build | If True, automatically launch the build. If one doesn't exist, download and extract the correct version. Set this to False to use your own build, or (if you are a backend developer) to use Unity Editor. | -| display | If launch_build == True, launch the build using this display number (Linux-only). | *** @@ -191,15 +190,11 @@ _Returns:_ The frame as an integer. *** -#### `launch_build(display: int = None) -> None` +#### `launch_build() -> None` _This is a static function._ Launch the build. If a build doesn't exist at the expected location, download one to that location. -| Parameter | Description | -| --- | --- | -| display | If launch_build == True, launch the build using this display number (Linux-only). | - *** diff --git a/Documentation/python/debug_controller.md b/Documentation/python/debug_controller.md index 51d2f4b98..41f7ba0e1 100644 --- a/Documentation/python/debug_controller.md +++ b/Documentation/python/debug_controller.md @@ -16,7 +16,7 @@ c.start() *** -#### `__init__(self, port: int = 1071, launch_build: bool = True, display: int = None)` +#### `__init__(self, port: int = 1071, launch_build: bool = True)` Create the network socket and bind the socket to the port. @@ -24,7 +24,6 @@ Create the network socket and bind the socket to the port. | --- | --- | | port | The port number. | | launch_build | If True, automatically launch the build. If one doesn't exist, download and extract the correct version. Set this to False to use your own build, or (if you are a backend developer) to use Unity Editor. | -| display | If launch_build == True, launch the build using this display number (Linux-only). | *** diff --git a/Python/tdw/controller.py b/Python/tdw/controller.py index 17aff8abe..adcb36ad2 100644 --- a/Python/tdw/controller.py +++ b/Python/tdw/controller.py @@ -25,14 +25,13 @@ class Controller(object): ``` """ - def __init__(self, port: int = 1071, check_version: bool = True, launch_build: bool = True, display: int = None): + def __init__(self, port: int = 1071, check_version: bool = True, launch_build: bool = True): """ Create the network socket and bind the socket to the port. :param port: The port number. :param check_version: If true, the controller will check the version of the build and print the result. :param launch_build: If True, automatically launch the build. If one doesn't exist, download and extract the correct version. Set this to False to use your own build, or (if you are a backend developer) to use Unity Editor. - :param display: If launch_build == True, launch the build using this display number (Linux-only). """ # Compare the installed version of the tdw Python module to the latest on PyPi. @@ -42,7 +41,7 @@ def __init__(self, port: int = 1071, check_version: bool = True, launch_build: b # Launch the build. if launch_build: - Controller.launch_build(display) + Controller.launch_build() context = zmq.Context() @@ -281,11 +280,9 @@ def get_frame(frame: bytes) -> int: return int.from_bytes(frame, byteorder='big') @staticmethod - def launch_build(display: int = None) -> None: + def launch_build() -> None: """ Launch the build. If a build doesn't exist at the expected location, download one to that location. - - :param display: If launch_build == True, launch the build using this display number (Linux-only). """ # Download the build. @@ -298,11 +295,7 @@ def launch_build(display: int = None) -> None: success = True # Launch the build. if success: - # Launch on the correct display. - if system() == "Linux" and display is not None: - Popen([f"DISPLAY=:{display}.0", str(Build.BUILD_PATH.resolve())]) - else: - Popen(str(Build.BUILD_PATH.resolve())) + Popen(str(Build.BUILD_PATH.resolve())) def _check_build_version(self, version: str = __version__, build_version: str = None) -> None: """ diff --git a/Python/tdw/debug_controller.py b/Python/tdw/debug_controller.py index ae8f48095..0dcefa992 100644 --- a/Python/tdw/debug_controller.py +++ b/Python/tdw/debug_controller.py @@ -18,19 +18,18 @@ class DebugController(Controller): ``` """ - def __init__(self, port: int = 1071, launch_build: bool = True, display: int = None): + def __init__(self, port: int = 1071, launch_build: bool = True): """ Create the network socket and bind the socket to the port. :param port: The port number. :param launch_build: If True, automatically launch the build. If one doesn't exist, download and extract the correct version. Set this to False to use your own build, or (if you are a backend developer) to use Unity Editor. - :param display: If launch_build == True, launch the build using this display number (Linux-only). """ # This will be used to record each list of commands sent to the build. self.record = [] - super().__init__(port=port, launch_build=launch_build, display=display) + super().__init__(port=port, launch_build=launch_build) def communicate(self, commands: Union[dict, List[dict]]) -> list: """