Reading and editing the script PAL wrote
A project's script is what the project does: which module it listens to, what it shows, what it plays. PAL writes it in TypeScript. You never have to read it, but you can, and knowing a few of its patterns makes it easier to ask PAL for exactly the change you want.
Where to find it
Open the project's details:
- Code shows the script itself. Under it, Logs shows the messages the script writes with
p.log. - Tweak shows the script's settings. Changing one there needs no new code.
To change what the script does, tell PAL in the project's chat. PAL rewrites the script and checks it before it reaches your board.
Everything goes through p
A script talks to your board through one object, p. p.onSensorChange listens to a module, p.log writes to the Logs, p.config reads the settings, and so on. The Script reference lists every one of them, generated from the same file PAL's scripts are checked against.
The three examples below are copied from Palpable's own project templates.
Settings live at the top
Every setting you see under Tweak starts as one entry in params at the top of the script. The script reads it as p.config.<name>. This is the Sounds switch from the home lights template (packages/skills/home-lights/template/home-controller.ts), shortened:
export const params = {
// …
sounds: { type: 'toggle', label: 'Sounds', default: true },
};And where the script uses it, further down the same file:
const tone = (frequency: number, ms: number) => {
if (p.config.sounds === false) return;
for (const part of PARTS.sound) part.tone(frequency, ms);
};In words: when Sounds is switched off, play nothing; otherwise play the tone on every part of the board that can make a sound. Because the script reads p.config.sounds each time, flipping the switch takes effect at once.
Reacting to a module
p.onSensorChange(module, reading, callback) runs the callback each time that module's reading changes. This is the button from the MIDI controller template (packages/skills/midi/template/midi-controller.ts):
p.onSensorChange('qwiic-button', 'button', (v) =>
v ? midi.press('button', p.config.buttonNote) : midi.release('button')
);In words: when the button goes down, play the note set in Button note; when it comes back up, let the note go. To make the button play a different note, change Button note under Tweak. To make it do something else entirely, ask PAL.
Waiting, and staying awake
Some calls take time: a sound that plays to its end, a question to a cloud service, a servo that moves. Those are written with await in front, and the script waits there until they finish. The last line of the MIDI controller template is one of them:
export default async function () {
// … everything the script sets up …
await p.waitUntilStopped();
}await p.waitUntilStopped() keeps the script running, so the listeners it set up keep reacting until you press Run again to stop the project.
A call the reference shows returning a Promise needs await. The one that matters most is p.connector, which asks a cloud service (the weather, your smart home) and gives back its answer: written without await, the script reads the answer before it arrives and every value in it is empty.