Merge pull request #104 from maejima-fumika/feature/add-gpio-to-website

Add guides and library reference to the website.

Author: maejima-fumika

cli/src/commands/project/create.ts

@@ -10,7 +10,7 @@ import * as fs from '../../core/fs';
 import { CommandHandler } from "../command";
 
 
-const MAIN_FILE_CONTENTS = `print('Hello world!')\n`;
+const MAIN_FILE_CONTENTS = `console.log('Hello world!')\n`;
 const GIT_IGNORE_CONTENTS = `**/dist/\n`;
 
 class CreateHandler extends CommandHandler {

lang/src/compiler/compiler.ts

@@ -353,7 +353,7 @@ class ESPIDFComponents {
     public readonly commonArchiveFilePaths: string[];
 
     private readonly COMPONENTS_PATH_PREFIX = /^.*microcontroller/;
-    private readonly COMMON_COMPONENTS = ["cxx", "newlib", "freertos", "esp_hw_support", "heap", "log", "soc", "hal", "esp_rom", "esp_common", "esp_system"];
+    private readonly COMMON_COMPONENTS = ["cxx", "newlib", "freertos", "esp_hw_support", "heap", "log", "soc", "hal", "esp_rom", "esp_common", "esp_system", "xtensa"];
     private readonly RUNTIME_DIR: string; 
     private readonly SDK_CONFIG_DIR: string;
 

website/docs/reference/libraries/gpio.md

@@ -0,0 +1,40 @@
+# Standard Libraries
+
+BlueScript follows a "Battery-included but removable" philosophy.
+Core features are kept minimal, while hardware drivers are provided as external standard libraries hosted on GitHub.
+
+To install any of these libraries, use the command:
+`bscript project install <git-url>`
+
+## Available Libraries
+
+Currently, the following libraries are available for stable use.
+
+### Digital I/O
+*   **GPIO (General Purpose Input/Output)**
+    *   Control pins, read digital states, and handle interrupts.
+    *   **Repository:** [https://github.com/bluescript-lang/pkg-gpio-esp32.git](https://github.com/bluescript-lang/pkg-gpio-esp32.git)
+    *   **Usage:** `import { GPIO } from "gpio";`
+
+---
+
+## Roadmap (Planned Libraries)
+
+We are actively developing drivers for the following peripherals.
+Support for these features will be rolled out in upcoming updates.
+
+| Category | Library | Status | Description |
+| :--- | :--- | :--- | :--- |
+| **Analog** | **ADC** | 🚧 Planned | Read analog sensor values. |
+| **Analog** | **DAC** | 🚧 Planned | Output analog voltage signals. |
+| **Control** | **PWM** | 🚧 Planned | Pulse Width Modulation for LEDs and Servos. |
+| **Comms** | **UART** | 🚧 Planned | Serial communication with other devices. |
+| **Comms** | **I2C** | 🚧 Planned | Interface with sensors and displays (Two-wire). |
+| **Comms** | **SPI** | 🚧 Planned | High-speed serial communication. |
+| **Audio** | **I2S** | 🚧 Planned | Digital audio data transfer. |
+| **Wireless** | **WiFi** | 🚧 Planned | Connect to the internet, make HTTP requests. |
+| **Wireless** | **Bluetooth** | 🚧 Planned | BLE communication (Central/Peripheral). |
+
+<!-- :::note Contribute?
+BlueScript is an open ecosystem. If you have wrapped an ESP-IDF component into a BlueScript package, feel free to share it with the community!
+::: -->

website/docs/reference/libraries/standard.md

@@ -0,0 +1,85 @@
+# Blink LED
+
+Now that you have verified your environment, let's move on to the "Real" Hello World of embedded systems: **Blinking an LED**.
+
+In this tutorial, you will learn:
+1.  How to install external packages.
+2.  How to wire an LED to the ESP32.
+3.  How to write code to control GPIO pins.
+
+## Step 1: Hardware Setup
+
+Depending on your hardware, choose one of the following setups.
+
+### Option A: Using the Onboard LED
+Most ESP32 development boards (like the ESP32-DevKitC) have a small blue LED built into the board.
+*   **Pin:** Typically **GPIO 2**.
+*   **Wiring:** No external wiring required.
+
+### Option B: Using an External LED
+If your board does not have an onboard LED, or if you prefer to build a circuit, connect an LED to **GPIO 23**.
+
+**Required Parts:**
+*   1x LED
+*   1x Resistor (220Ω - 1kΩ)
+*   Breadboard and Jumper wires
+
+:::tip Polarity Check
+Make sure to connect the **longer leg** (Anode) of the LED towards the GPIO pin (through the resistor), and the **shorter leg** (Cathode) to GND.
+:::
+
+## Step 2: Install GPIO Package
+
+BlueScript keeps the core runtime small. To use hardware features like GPIO, we need to install the driver package.
+
+Run the following command in your project directory:
+
+```bash
+bscript project install https://github.com/bluescript-lang/pkg-gpio-esp32.git
+```
+
+## Step 3: Write Code
+
+Open `index.bs` and replace its content with the code below.
+
+This program will blink the LED 10 times with a 1-second interval.
+
+:::warning Select your Pin
+The code below uses **GPIO 2** (Onboard LED).
+If you are using the **External LED**, change `2` to `23` in the `new GPIO(...)` line.
+:::
+
+```typescript title="index.bs"
+// Import GPIO class and Enums from the installed package
+import { GPIO, PinMode, PinLevel } from "gpio";
+
+// Initialize GPIO 2 as Input/Output mode
+// CHANGE THIS TO '23' IF USING EXTERNAL LED
+const led = new GPIO(2, PinMode.InputOutput);
+
+console.log("Starting Blink Loop...");
+
+// Blink the LED 10 times
+for (let i = 0; i < 10; i++) {
+    // Turn LED ON
+    led.write(PinLevel.High);
+    time.delay(1000); // Wait for 1000ms (1 second)
+
+    // Turn LED OFF
+    led.write(PinLevel.Low);
+    time.delay(1000);
+}
+
+led.close();
+console.log("Finished!");
+```
+
+## Step 4: Run
+
+Make sure your device is powered on and run:
+
+```bash
+bscript project run
+```
+
+You should see the LED turn on and off every second!

website/docs/tutorial/examples/blink-led.md

@@ -49,6 +49,9 @@ bscript project run
 Please note that programs uploaded via `bscript project run` are **not persisted** after a reboot.
 
 If you restart or power off the device, the program will be lost. You will need to execute `bscript project run` again to re-upload your code.
+
+**Future Roadmap:**
+We are planning to introduce a **`bscript project deploy`** command. This command will permanently install your application, allowing it to start automatically when the device powers on.
 :::
 
 :::tip Try the REPL
@@ -58,10 +61,3 @@ Run **`bscript repl`** in your terminal. You can type commands like `console.log
 :::
 
 ---
-
-## Next Steps
-
-Now that you have the basics down, explore what else BlueScript can do:
-
-*   **[Language Reference](../../reference/language/intro)**: Learn about supported syntax, Inline C, and hardware APIs.
-*   **[CLI Reference](../../reference/cli)**: Discover advanced commands.

website/docs/tutorial/get-started/blink-led.md

@@ -1,5 +1,9 @@
 # Set up your environment
 
+:::danger macOS Only
+Currently, BlueScript strictly requires **macOS**. Windows and Linux support is under development.
+:::
+
 In this guide, we will install the BlueScript CLI and flash the runtime environment to your microcontroller.
 
 Currently, only **ESP32 development boards** are supported.
@@ -12,9 +16,8 @@ Before we begin, ensure you have the following:
   - **Host PC:** A laptop running **macOS** (Windows and Linux are currently **not** supported).
   - **Micocontroller:** An ESP32 development board (e.g., ESP32-DevKitC)
   - **USB cable** to connect your host PC and the microcontroller 
-- **Software**
+- **Software:**
   - [Node.js](https://nodejs.org/) (v20 or later) installed on your host PC.
-
 ---
 
 ## Step 1: Install the CLI
@@ -58,12 +61,12 @@ Connect your ESP32 to your computer via USB and flash the runtime:
 bscript board flash-runtime esp32
 ```
 
-If the flash is successful, your device is now ready to receive BlueScript code wirelessly!
-
----
+The CLI will display a list of detected serial ports. Use the arrow keys to select the one corresponding to your ESP32 (e.g., /dev/tty.usbserial-xxxx).
 
-## Next Steps
+:::info Device not found?
+If your device does not appear in the list, you may need to install USB-to-UART drivers (e.g., [CP210x](https://www.silabs.com/software-and-tools/usb-to-uart-bridge-vcp-drivers) or [FTDI](https://ftdichip.com/drivers/vcp-drivers/)).
 
-Now that your device is set up, let's create your first project.
+See also [Establish Serial Connection with ESP32](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/establish-serial-connection.html).
+:::
 
-👉 **[Go to: Create project and Run](./create-project-and-run)**
+If the flash is successful, your device is now ready to receive BlueScript code wirelessly!

website/docs/tutorial/get-started/create-project-and-run.md

@@ -0,0 +1,81 @@
+# Imports & Includes
+
+As your project grows, you will want to split your code into multiple files.
+BlueScript handles dependencies differently depending on whether you are loading **BlueScript Modules** or raw **C Source Files**.
+
+## Importing BlueScript Modules
+
+You can create reusable BlueScript code (`.bs` files) and import them into other files.
+
+### 1. Local Modules
+To import a module from your own project, use the **relative path** (starting with `./` or `../`).
+
+**`math-utils.bs`** (The library)
+```typescript
+// Named export
+export function add(a: integer, b: integer): integer {
+    return a + b;
+}
+
+// ❌ Default export is NOT supported
+// export default function ...
+```
+
+**`index.bs`** (The importer)
+```typescript
+// Import using relative path
+import { add } from "./math-utils";
+
+console.log(add(10, 20));
+```
+
+:::warning No Default Exports
+BlueScript currently supports only **Named Exports**.
+You must use `import { name }` syntax. `import name from ...` will not work.
+:::
+
+### 2. Package Modules
+When you install an external library (like a driver), you import it by its **Package Name**, not a file path.
+
+```typescript
+// Import from an installed package
+// The compiler resolves "gpio" from your project config
+import { GPIO } from "gpio";
+```
+
+## Including C Files
+
+If you have standalone C source files (`.c`) in your project, you can include them using **Inline C**.
+
+Unlike standard C compilers, BlueScript's `code` block treats `#include` paths relative to the current file when using quotes.
+
+**`native-lib.c`**
+```c
+// A pure C function
+int native_multiply(int a, int b) {
+    return a * b;
+}
+```
+
+**`index.bs`**
+```typescript
+// Include the local C file
+code`#include "./native-lib.c"`
+
+export function multiply(a: integer, b: integer): integer {
+    let result = 0;
+    // Call the function defined in the included C file
+    code`${result} = native_multiply(${a}, ${b});`
+    return result;
+}
+
+console.log(multiply(3, 4));
+```
+
+### Summary table
+
+| Source Type | Syntax | Path Style | Example |
+| :--- | :--- | :--- | :--- |
+| **Local BS Module** | `import { ... }` | Relative | `"./utils"` |
+| **Package BS Module** | `import { ... }` | Package Name | `"gpio"` |
+| **Local C File** | `code`\`#include ...\` | Relative | `"./driver.c"` |