support for setting music pin using analogSetPitchPin

docs/reference/music/play-tone.md

@@ -25,6 +25,15 @@ let freq = music.noteFrequency(Note.C)
 music.playTone(freq, 1000)
 ```
 
+
+### Using other pins
+
+Use [analogSetPitchPin](/pins/analog-set-pitch-pin) to change that pin used to generate music.
+
+```blocks
+pins.analogSetPitchPin(AnalogPin.P1);
+```
+
 ### See also
 
 [rest](/reference/music/rest), [ring tone](/reference/music/ring-tone) , [tempo](/reference/music/tempo), [set tempo](/reference/music/set-tempo), 

docs/reference/music/ring-tone.md

@@ -32,6 +32,14 @@ basic.forever(() => {
 })
 ```
 
+### Using other pins
+
+Use [analogSetPitchPin](/pins/analog-set-pitch-pin) to change that pin used to generate music.
+
+```blocks
+pins.analogSetPitchPin(AnalogPin.P1);
+```
+
 ### See also
 
 [rest](/reference/music/rest), [play tone](/reference/music/play-tone),

docs/reference/pins/analog-pitch.md

@@ -1,6 +1,7 @@
 # Analog Pitch
 
-Emits a Pulse With Modulation (PWM) signal to the current pitch [pin](/device/pins). Use [analog set pitch pin](/reference/pins/analog-set-pitch-pin) to set the current pitch pin.
+Emits a Pulse With Modulation (PWM) signal to the pin ``P0``.
+Use [analog set pitch pin](/reference/pins/analog-set-pitch-pin) to set the current pitch pin.
 
 ```sig
 pins.analogPitch(440, 300)
@@ -17,6 +18,7 @@ pins.analogPitch(440, 300)
 pins.analogSetPitchPin("P0")
 let frequency1 = 440
 let duration = 1000
+pins.analogSetPitchPin(AnalogPin.P1);
 pins.analogPitch(frequency1, duration)
 ```
 

libs/core/_locales/core-jsdoc-strings.json

@@ -179,15 +179,15 @@
   "music.tempo": "Returns the tempo in beats per minute. Tempo is the speed (bpm = beats per minute) at which notes play. The larger the tempo value, the faster the notes will play.",
   "pins": "Control currents in Pins for analog/digital signals, servos, i2c, ...",
   "pins.analogPitch": "Emits a Pulse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.",
-  "pins.analogPitch|param|frequency": "TODO",
+  "pins.analogPitch|param|frequency": "frequency to modulate in Hz.",
-  "pins.analogPitch|param|ms": "TODO",
+  "pins.analogPitch|param|ms": "duration of the pitch in milli seconds.",
   "pins.analogReadPin": "Read the connector value as analog, that is, as a value comprised between 0 and 1023.",
   "pins.analogReadPin|param|name": "pin to write to",
   "pins.analogSetPeriod": "Configures the Pulse-width modulation (PWM) of the analog output to the given value in **microseconds** or `1/1000` milliseconds.\nIf this pin is not configured as an analog output (using `analog write pin`), the operation has no effect.",
   "pins.analogSetPeriod|param|micros": "period in micro seconds. eg:20000",
   "pins.analogSetPeriod|param|name": "analog pin to set period to",
-  "pins.analogSetPitchPin": "Sets the pin used when using `pins->analog pitch`.",
+  "pins.analogSetPitchPin": "Sets the pin used when using `analog pitch` or music.",
-  "pins.analogSetPitchPin|param|name": "TODO",
+  "pins.analogSetPitchPin|param|name": "pin to modulate pitch from",
   "pins.analogWritePin": "Set the connector value as analog. Value must be comprised between 0 and 1023.",
   "pins.analogWritePin|param|name": "pin name to write to",
   "pins.analogWritePin|param|value": "value to write to the pin between ``0`` and ``1023``. eg:1023,0",

libs/core/_locales/core-strings.json

@@ -146,8 +146,10 @@
   "music.setTempo|block": "set tempo to (bpm)|%value",
   "music.tempo|block": "tempo (bpm)",
   "music|block": "music",
+  "pins.analogPitch|block": "analog pitch %frequency|for (ms) %ms",
   "pins.analogReadPin|block": "analog read|pin %name",
   "pins.analogSetPeriod|block": "analog set period|pin %pin|to (µs)%micros",
+  "pins.analogSetPitchPin|block": "analog set pitch pin %name",
   "pins.analogWritePin|block": "analog write|pin %name|to %value",
   "pins.digitalReadPin|block": "digital read|pin %name",
   "pins.digitalWritePin|block": "digital write|pin %name|to %value",

libs/core/music.ts

@@ -138,7 +138,6 @@ namespace music {
     //% blockId=device_play_note block="play|tone %note=device_note|for %duration=device_beat" icon="\uf025" blockGap=8
     //% parts="headphone"
     export function playTone(frequency: number, ms: number): void {
-        pins.analogSetPitchPin(AnalogPin.P0);
         pins.analogPitch(frequency, ms);
     }
 
@@ -150,7 +149,6 @@ namespace music {
     //% blockId=device_ring block="ring tone (Hz)|%note=device_note" icon="\uf025" blockGap=8
     //% parts="headphone"
     export function ringTone(frequency: number): void {
-        pins.analogSetPitchPin(AnalogPin.P0);
         pins.analogPitch(frequency, 0);
     }
 

libs/core/pins.cpp

@@ -147,7 +147,7 @@ namespace pins {
     /**
     * Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either ``high`` or ``low``.
     */
-    //% help=pins/on-pulsed weight=22 blockGap=8
+    //% help=pins/on-pulsed weight=22 blockGap=8 advanced=true
     //% blockId=pins_on_pulsed block="on|pin %pin|pulsed %pulse"
     void onPulsed(DigitalPin name, PulseValue pulse, Action body) {
         MicroBitPin* pin = getPin((int)name);
@@ -160,7 +160,7 @@ namespace pins {
     /**
     * Gets the duration of the last pulse in micro-seconds. This function should be called from a ``onPulsed`` handler.
     */
-    //% help=pins/pulse-duration
+    //% help=pins/pulse-duration advanced=true
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
     //% weight=21 blockGap=8
     int pulseDuration() {
@@ -174,7 +174,7 @@ namespace pins {
     * @param maximum duration in micro-seconds
     */    
     //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
-    //% weight=20
+    //% weight=20 advanced=true
     int pulseIn(DigitalPin name, PulseValue value, int maxDuration = 2000000) {
         MicroBitPin* pin = getPin((int)name);
         if (!pin) return 0;
@@ -223,22 +223,25 @@ namespace pins {
     MicroBitPin* pitchPin = NULL;
 
     /**
-     * Sets the pin used when using `pins->analog pitch`.
+     * Sets the pin used when using `analog pitch` or music.
-     * @param name TODO
+     * @param name pin to modulate pitch from
      */
-    //% help=pins/analog-set-pitch weight=12
+    //% blockId=device_analog_set_pitch_pin block="analog set pitch pin %name"
+    //% help=pins/analog-set-pitch weight=3 advanced=true
     void analogSetPitchPin(AnalogPin name) { 
       pitchPin = getPin((int)name);
     }
 
     /**
      * Emits a Pulse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
-     * @param frequency TODO
+     * @param frequency frequency to modulate in Hz.
-     * @param ms TODO
+     * @param ms duration of the pitch in milli seconds.
      */
-    //% help=pins/analog-pitch weight=14 async
+    //% blockId=device_analog_pitch block="analog pitch %frequency|for (ms) %ms"
+    //% help=pins/analog-pitch weight=4 async advanced=true blockGap=8
     void analogPitch(int frequency, int ms) { 
-      if (pitchPin == NULL) return;
+      if (pitchPin == NULL) 
+        analogSetPitchPin(AnalogPin::P0);
       if (frequency <= 0) {
         pitchPin->setAnalogValue(0);
       } else {
@@ -260,7 +263,7 @@ namespace pins {
     * @param name pin to set the pull mode on
     * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone 
     */
-    //% help=pins/set-pull weight=3
+    //% help=pins/set-pull weight=3 advanced=true
     //% blockId=device_set_pull block="set pull|pin %pin|to %pull"
     void setPull(DigitalPin name, PinPullMode pull) {
         PinMode m = pull == PinPullMode::PullDown 
@@ -311,7 +314,7 @@ namespace pins {
     * Write to the SPI slave and return the response
     * @param value Data to be sent to the SPI slave
     */
-    //% help=pins/spi-write weight=5
+    //% help=pins/spi-write weight=5 advanced=true
     //% blockId=spi_write block="spi write %value"
     int spiWrite(int value) {
         auto p = allocSPI();

libs/core/pins.ts

@@ -21,7 +21,7 @@ namespace pins {
     /**
      * Read one number from 7-bit I2C address.
      */
-    //% help=pins/i2c-read-number blockGap=8
+    //% help=pins/i2c-read-number blockGap=8 advanced=true
     //% blockId=pins_i2c_readnumber block="i2c read number|at address %address|of format %format=i2c_sizeof" weight=7
     export function i2cReadNumber(address: number, format: NumberFormat): number {
         let buf = pins.i2cReadBuffer(address, pins.sizeOf(format))
@@ -31,7 +31,7 @@ namespace pins {
     /**
      * Write one number to a 7-bit I2C address.
      */
-    //% help=pins/i2c-write-number blockGap=8
+    //% help=pins/i2c-write-number blockGap=8 advanced=true
     //% blockId=i2c_writenumber block="i2c write number|at address %address|with value %value|of format %format=i2c_sizeof" weight=6
     export function i2cWriteNumber(address: number, value: number, format: NumberFormat): void {
         let buf = createBuffer(pins.sizeOf(format))

libs/core/shims.d.ts

@@ -557,14 +557,14 @@ declare namespace pins {
     /**
      * Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either ``high`` or ``low``.
      */
-    //% help=pins/on-pulsed weight=22 blockGap=8
+    //% help=pins/on-pulsed weight=22 blockGap=8 advanced=true
     //% blockId=pins_on_pulsed block="on|pin %pin|pulsed %pulse" shim=pins::onPulsed
     function onPulsed(name: DigitalPin, pulse: PulseValue, body: () => void): void;
 
     /**
      * Gets the duration of the last pulse in micro-seconds. This function should be called from a ``onPulsed`` handler.
      */
-    //% help=pins/pulse-duration
+    //% help=pins/pulse-duration advanced=true
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
     //% weight=21 blockGap=8 shim=pins::pulseDuration
     function pulseDuration(): number;
@@ -576,7 +576,7 @@ declare namespace pins {
      * @param maximum duration in micro-seconds
      */
     //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
-    //% weight=20 maxDuration.defl=2000000 shim=pins::pulseIn
+    //% weight=20 advanced=true maxDuration.defl=2000000 shim=pins::pulseIn
     function pulseIn(name: DigitalPin, value: PulseValue, maxDuration?: number): number;
 
     /**
@@ -599,18 +599,20 @@ declare namespace pins {
     function servoSetPulse(name: AnalogPin, micros: number): void;
 
     /**
-     * Sets the pin used when using `pins->analog pitch`.
+     * Sets the pin used when using `analog pitch` or music.
-     * @param name TODO
+     * @param name pin to modulate pitch from
      */
-    //% help=pins/analog-set-pitch weight=12 shim=pins::analogSetPitchPin
+    //% blockId=device_analog_set_pitch_pin block="analog set pitch pin %name"
+    //% help=pins/analog-set-pitch weight=3 advanced=true shim=pins::analogSetPitchPin
     function analogSetPitchPin(name: AnalogPin): void;
 
     /**
      * Emits a Pulse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
-     * @param frequency TODO
+     * @param frequency frequency to modulate in Hz.
-     * @param ms TODO
+     * @param ms duration of the pitch in milli seconds.
      */
-    //% help=pins/analog-pitch weight=14 async shim=pins::analogPitch
+    //% blockId=device_analog_pitch block="analog pitch %frequency|for (ms) %ms"
+    //% help=pins/analog-pitch weight=4 async advanced=true blockGap=8 shim=pins::analogPitch
     function analogPitch(frequency: number, ms: number): void;
 
     /**
@@ -618,7 +620,7 @@ declare namespace pins {
      * @param name pin to set the pull mode on
      * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone 
      */
-    //% help=pins/set-pull weight=3
+    //% help=pins/set-pull weight=3 advanced=true
     //% blockId=device_set_pull block="set pull|pin %pin|to %pull" shim=pins::setPull
     function setPull(name: DigitalPin, pull: PinPullMode): void;
 
@@ -645,7 +647,7 @@ declare namespace pins {
      * Write to the SPI slave and return the response
      * @param value Data to be sent to the SPI slave
      */
-    //% help=pins/spi-write weight=5
+    //% help=pins/spi-write weight=5 advanced=true
     //% blockId=spi_write block="spi write %value" shim=pins::spiWrite
     function spiWrite(value: number): number;
 }