DESIREs2EmbodiedBDIAgt
=====================

Reproducibility package for the experiments presented in
"Interoception and Beyond: What Can an Embodied BDI Agent Desire?" (AAMAS 2027).

1. DOWNLOAD
-----------
Download the reproducibility archive:
https://underreview.doubleblind.cloudns.nz/DESIREs2EmbodiedBDIAgt/reproducibility.zip

On Debian, download and extract it with:

  wget https://underreview.doubleblind.cloudns.nz/DESIREs2EmbodiedBDIAgt/reproducibility.zip
  unzip reproducibility.zip
  cd DESIREs2EmbodiedBDIAgt

If the archive extracts to a differently named folder, enter the folder containing run.sh.

2. REQUIREMENTS
---------------
- Operating system: Debian GNU/Linux 12 or 13
- Java: OpenJDK 21
- Hardware: Arduino Uno connected by USB
- USB/serial-port access permissions for the Arduino board

The deployment script checks for Arduino CLI, the Arduino AVR core, and the NECK library, installing them when absent. It may request sudo privileges to install Arduino CLI.

3. PROJECT STRUCTURE
--------------------
DESIREs2EmbodiedBDIAgt/
|-- JACAMOb.jar
|-- run.sh
|-- testTrieb.jcm
|-- logging.properties
|-- src/
|   |-- agt/
|   |   |-- common/ (aamas.asl, bathroom.asl)
|   |   |-- unbodied.asl
|   |   |-- onlyBelief.asl
|   |   `-- onlyDesire.asl
|   |-- bdy/
|   |   |-- deployBody.sh
|   |   |-- firmware/firmware.ino
|   |   `-- neck2arduino.zip
|   `-- env/aamas/ (Program.java)
|-- log/
|   |-- unbodied/ (mas-*.log, results.txt)
|   |-- onlyBelief/ (mas-*.log, results.txt)
|   |-- onlyDesire/ (mas-*.log, results.txt)
|   |-- parser.sh
|   `-- results.ods
`-- target/classes/aamas/Program.class

4. RUNNING THE EXPERIMENTS
--------------------------
Connect the Arduino Uno to the computer via USB. From the project root:

  ./run.sh

The script checks or installs Arduino CLI, detects the board, checks or installs the Arduino AVR core and NECK library from the bundled ZIP, compiles the firmware, uploads it to the Arduino, and starts the JaCaMo multi-agent system. Keep the board connected while running the experiment.

5. EXPERIMENTAL CONFIGURATIONS
------------------------------
- unbodied.asl: BDI agent without bodily integration.
- onlyBelief.asl: Embodied BDI agent that incorporates interoceptive bodily states into beliefs.
- onlyDesire.asl: Embodied BDI agent using the proposed Trieb/Drang desire mechanism.

By default, onlyDesire is enabled. To run another configuration, edit testTrieb.jcm: comment out the active configuration, uncomment the desired configuration, save, and run ./run.sh again. Enable only one configuration at a time.

6. LOGS AND RESULTS
-------------------
Each configuration directory under log/ contains ten execution logs (mas-0.log through mas-9.log) and a results.txt file. The log/parser.sh script extracts BDI-cycle and SENSE, PLAN, and ACT metrics. Example:

  cd log
  ./parser.sh onlyDesire/mas-0.log

The file log/results.ods contains consolidated experimental results.

7. REPRODUCIBILITY NOTES
------------------------
- Intended environment: Debian 12/13 with Java 21.
- Arduino Uno hardware is required for deployment.
- The NECK library is bundled as src/bdy/neck2arduino.zip.
- Existing installations of Arduino CLI, AVR core, and NECK are reused when detected.
- Only one experiment configuration should be enabled at a time.
