cee/pins

Overview

The cee/pins section of the cee API provides access to and control over pin-based hardware interfaces on ComputerCraft computers. These pins are used for connecting to external devices, sensors, and peripherals using a standardized pin system that supports both digital and analog signals.

This section allows users to: - Read from and write to individual digital pins. - Read analog values from analog-capable pins. - Configure pin modes (input/output). - Manage internal hardware connections via the cee namespace.

Pins can be accessed through global functions prefixed with cee. when dealing with system-level or direct hardware control. Alternatively, they may be managed as part of a device object if working within an abstraction layer (e.g., via device.getPin()).

⚠️ Important: Pins are typically associated with physical or virtual hardware components and must be properly initialized before use. Not all pins support all operations — some are read-only, others write-only, and certain pins may have restrictions based on their hardware capabilities.

Calling Conventions / Prefixes

All functions in the pins section are available under the global cee namespace unless otherwise specified:

-- Global function call
local value = cee.getPin(1)
cee.setPin(1, true)

-- Object-based usage (if applicable)
local pin = device.getPin(1)
pin:read()
pin:write(true)

Functions in this section include: - cee.getPin(pin) – Read the current state of a digital pin. - cee.setPin(pin, value) – Set the output state of a digital pin. - cee.analogRead(pin) – Read an analog voltage level from a supported pin. - cee.pinMode(pin, mode) – Configure the operating mode of a pin (input/output). - cee.getPinMode(pin) – Get the current configuration mode of a pin.

These functions assume a standard pin numbering convention where pins are numbered starting from 1 and increasing upward. For example, pin 1 corresponds to the first physical or logical pin on the device.

API Reference Table

Signature	Arguments	Return Type	Description
`cee.getPin(pin)`	`pin: number`	`boolean`	Returns the current digital state (true/false) of the specified pin.
`cee.setPin(pin, value)`	`pin: number`, `value: boolean`	`nil`	Sets the output state of the specified digital pin.
`cee.analogRead(pin)`	`pin: number`	`number`	Reads an analog voltage level from the specified pin (0–15).
`cee.pinMode(pin, mode)`	`pin: number`, `mode: string`	`nil`	Sets the mode of a pin to either `"input"` or `"output"`.
`cee.getPinMode(pin)`	`pin: number`	`string`	Returns the current mode of the specified pin (`"input"` or `"output"`).

⚠️ Note: Analog reads return values from 0 to 15, which may represent a scaled voltage range depending on the hardware implementation.

Lua Code Examples

Example 1: Reading and Writing Digital Pins

-- Configure pin 5 as output
cee.pinMode(5, "output")

-- Turn pin 5 ON (true)
cee.setPin(5, true)

-- Wait a bit
os.sleep(1)

-- Turn pin 5 OFF (false)
cee.setPin(5, false)

-- Read the state of pin 3 (assumed to be input)
local state = cee.getPin(3)
print("Pin 3 is:", state and "ON" or "OFF")

Example 2: Analog Input

-- Configure pin 7 as input
cee.pinMode(7, "input")

-- Read analog value from pin 7 (0–15 scale)
local analogValue = cee.analogRead(7)
print("Analog value:", analogValue)

Example 3: Toggle Pin State

local ledPin = 4

-- Initialize as output
cee.pinMode(ledPin, "output")

-- Toggle the LED on and off repeatedly
for i = 1, 5 do
    cee.setPin(ledPin, true)
    os.sleep(0.5)
    cee.setPin(ledPin, false)
    os.sleep(0.5)
end

Example 4: Safe Pin Access

local pin = 2

-- Check if the pin is configured for input before reading
if cee.getPinMode(pin) == "input" then
    local value = cee.getPin(pin)
    print("Value on pin", pin, "is", value)
else
    print("Pin", pin, "not configured for input")
end

Example 5: Error Handling

local function safeRead(pin)
    if not pcall(function() return cee.getPin(pin) end) then
        print("Invalid or unsupported pin:", pin)
        return nil
    end
    return cee.getPin(pin)
end

-- Usage:
local result = safeRead(10)
if result ~= nil then
    print("Value read successfully:", result)
end

Notes

Pins must be configured using pinMode() before attempting to read or write them.
Not all pins support analog reading; only those marked as analog-capable will return valid values.
Using invalid pin numbers results in an error or undefined behavior.
Analog inputs should not be used for high-frequency signal detection due to sampling limitations.