diff --git a/Component-Modem.md b/Component-Modem.md new file mode 100644 index 0000000..6a2d390 --- /dev/null +++ b/Component-Modem.md @@ -0,0 +1,43 @@ +This component is provided by [[network cards|Items#network-card]]. Wireless network cards behave much like normal network cards, but additionally send the message as a wireless "packet" when a strength is set. + +Component name: `modem`. +Callbacks: +- `isWireless(): boolean` + Returns whether this modem is capable of sending wireless messages. +- `isOpen(port: number): boolean` + Returns whether the specified "port" is currently being listened on. Messages only trigger signals when they arrive on a port that is open. +- `open(port: number): boolean` + Opens the specified port number for listening. Returns `true` if the port was opened, `false` if it was already open. +- `send(address: string, port: number[, ...]): boolean` + Sends a network message to the specified address. Returns `true` if the message was sent. This does *not* mean the message was received, only that it was sent. No port-sniffing for you. + Any additional arguments are passed along as data. These arguments must be basic types: nil, boolean, number and string values are supported, tables and functions are not. See [[the text API|API/Text]] for serialization of tables. +- `broadcast(port: number, ...): boolean` + Sends a broadcast message. This message is delivered to all reachable network cards. Returns `true` if the message was sent. Note that broadcast messages are *not* delivered to the modem that sent the message. + All additional arguments are passed along as data. See `send`. +- `getStrength(): number` + The current signal strength to apply when sending messages. + *Wireless network cards only.* +- `setStrength(value: number): number` + Sets the signal strength. If this is set to a value larger than zero, sending a message will also generate a wireless message. The higher the signal strength the more energy is required to send messages, though. + *Wireless network cards only.* + +This component generates a signal named `modem_message` if a message from another network card is received. It has the signature `localAddress: string, remoteAddress: string, port: number, distance: number, ...`. +- `localAddress` is the address of the modem component the message was received by. +- `remoteAddress` is the address of the network card the message was sent from. +- `port` is the port number the message was delivered to. +- `distance` is the distance to the modem that sent the message. This is only set for wireless messages. For normal messages this is always 0. +- All further values are values passed along by the sender (i.e. the `...` in `send` and `broadcast`). + +*A note on HTTP requests*: if enabled in the configuration, wireless modems can be used to make HTTP requests. For this, call `send` with a URL instead of a component address. The recommended way of doing this is via the [[HTTP API|API/HTTP]], however. + +Example use: +```lua +local m = component.modem -- get primary modem component +m.open(123) +print(m.isOpen(123)) -- true +-- Send some message. +m.broadcast(321, "this is a test") +-- Wait for a message from another network card. +local _, from, port, _, message = event.pull("modem_message") +print("Got a message from " .. from .. " on port " .. port .. ": " .. tostring(message)) +``` \ No newline at end of file